Search documentation...

K

Live debugger

Overview

Hightouch provides a live debugger to provide visibility into each of your sync executions or "runs." The debugger shows all requests and responses Hightouch made to your destination during a sync run. You can access the debugger from the Runs tab of any sync's overview page.

Hightouch stores row-level sync run data for seven days. If you need older logs, consider using Warehouse Sync logs.

View run details

You can see a table of recent sync runs and their statuses and other details from the Runs tab of any sync's overview page. Click the run to view more detailed information and access the debugger.

View run details

This run detail page shows the number of successful and rejected rows and breaks successful and rejected rows down into added, changed, or removed rows.

  • Added means the query results returned a new row that the sync added or tried to add to the destination.
  • Changed means the row appeared in the query results but had updated values compared to the previous run.
  • Removed means the row was no longer in the query results, and the sync removed or tried to remove it from the destination.

View the status of a sync

Sync run status

The preceding example sync run has a healthy status, meaning the sync ran as expected without any rejected rows.

The example sync run below has a failed status, meaning it didn't execute as intended.

View rejected rows

This final example run has a warning status, meaning the destination rejected at least one row.

View rejected rows

View error messages

To view an error message for an entire run that failed, click View error from the Runs overview tab or View run error from a run's details page.

View error message

Hightouch displays error messages in the format third-party APIs send them, including standard HTTP status codes and any trace IDs, if the third party provides them.

Example error message

To see a specific row's error message, click View error on the row in the run's detail page table:

Not found error message

Hightouch displays error messages provided by the third-party API related to individual rows.

Example row-level error message

Filter runs

To narrow down the runs to inspect, you can use the Filter option to hide runs with either zero operations or zero successful operations.

Filtering runs

Search rows

Use the search input above the run details table to find a row with a primary key that matches the search value. This search only searches through the column you selected as the model's primary key.

Search rows

Export rows and row errors

You can also export the data from all rows or just row errors as a CSV or JSON file.

Export rows

You can then inspect the file to see details of rows the sync run added, changed, or deleted:

Inspect CSV

Or, download and then inspect just the row errors:

Inspect CSV row errors

Use your CSV editor's search feature to locate rows or specific error messages more quickly.

Use the live debugger

To take a closer look at the individual HTTP requests and responses that comprise a sync run, click any row to open the live debugger.

Launch live debugger

The live debugger shows the request and response JSON payloads of which the row was part and the other rows that were part of the batch.

Live Debug Rows

In this example, the POST request to update this batch failed because of a 400 error. The response displays the third-party error message saying there was an undefined object in the request:

Debugging POST error

Hightouch displays the request's URL for diagnostic purposes. An undefined sub-URL means that the row ID number needed for this POST request failed to populate the URL. The next step would be to inspect the query results returned from the model.

Undefined URL error

Payload inspection

To expand a payload for closer inspection, click the expand icon in the top right corner of the payload viewer.

Expand the payload

Once expanded, you can scroll through the payload or click in the payload body and use Ctrl/Command-F to open a search window. Use the search window to find row IDs, email addresses, or any other payload data you need to inspect or trace.

To copy the payload, click the copy button in the top right corner of the payload viewer; the browser saves the payload to your clipboard.

Copying the payload

For large, nested JSON payloads, it's helpful to paste the JSON into a viewer like CodeBeautify to view the payload's structure and values. Click Tree viewer to inspect the JSON as collapsible properties:

Viewing JSON in Code Beautify

Hightouch debugging tips

Filter runs

When you have a large number of runs to inspect, use the run filter to narrow down your view to only the runs you want to inspect.

Use run filters

Run timestamps

Use the run timestamps to isolate the runs you need to inspect based on your observation of when an error occurred. Run timestamps appear in your local timezone under the header Started.

Use run timestamps

Search the live debugger

Use the live debugger to search payloads for missing rows or to see how Hightouch sent the data to your destination. Expand the payload viewer and use command+F to search for entities you need to inspect.

Search error messages

Hightouch returns error messages directly from third-party APIs as they occur. Therefore, you will likely find more information and solutions by copying and pasting the error message into your favorite search engine or Stack Overflow.

Some destinations also have active developer communities where you can find explanations for common error messages:

Understand HTTP status codes

Hightouch displays any HTTP status codes your destination includes in the HTTP response. These universal status codes can help you understand what may have gone wrong with your sync. If you see an HTTP status code in your Hightouch error message, it comes from your destination, not from Hightouch.

HTTP status codes are grouped into five categories:

  • 1xx Informational Response: The destination request was received and understood. Request processing continues.
  • 2xx Success: The request was successfully received, understood, and accepted.
  • 3xx Redirection: The client must take further action to complete the request.
  • 4xx Client Errors: The client caused an error. The request contains the wrong syntax or can't be fulfilled.
  • 5xx Server Errors: The server encountered an error and failed to fulfill the request.

See Mozilla's documentation for further information on HTTP status codes.

Common status codes in Hightouch

The most common status codes Hightouch syncs receive are:

  • 200 success: This is good news and means your destination successfully received and accepted the request from Hightouch.

  • 400 status: A 400 error often means there is invalid data. Check that your data conforms to the destination's formatting expectations by referring to the destination's API documentation.

  • 401 status: A 401 error often means there is a problem with the credentials you've used to set up your destination. Check that your credentials have the correct permissions to access the destination.

Search the live debugger

500 series (500, 502, 504, etc.) errors are "server errors," meaning something has gone wrong within the destination you are trying to sync to. Visit the status page of the destination to see if there are any reported outages, for example, Slack System Status or HubSpot Status.

If a sync fails because of a destination server error, Hightouch retries the sync.

Data types and casting

Third-party APIs require the data you send to be of a specific data type. Unless otherwise specified, Hightouch takes the data from your source and leaves the data type unchanged to send to your destination. See the data types and casting docs for tips on resolving data type incompatibilities.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Mar 18, 2023

On this page

OverviewView run detailsView error messagesFilter runsSearch rowsExport rows and row errorsUse the live debuggerPayload inspectionHightouch debugging tipsFilter runsRun timestampsSearch the live debuggerSearch error messagesUnderstand HTTP status codesData types and casting

Was this page helpful?