How to Use Logs to Troubleshoot a Sync Failure

Sync failures are rare but can be frustrating. However, error logs serve as invaluable resources for diagnosing and troubleshooting these issues when they occur.

If a connection's sync fails, you can often identify the root cause of the error from the "Failure Origin" message listed for that sync in the connection's "Job History" tab or if the failed sync was the last job that was run on the connection, the error will display in the "Status" tab.

Screen Shot 2023-07-19 at 2.21.09 PM.png

Screen Shot 2023-07-18 at 4.45.42 PM.png

This should show where the error originated, normally in the source or destination, but can sometimes occur during replication or from an airbyte_platform issue. In addition to where the failure occurred, this message often includes helpful information about the error.

In the example above from a Facebook Marketing <> BigQuery connection, the error message shows the origin of the failure came from the source, which in this case is Facebook Marketing. The message gives a bit more context and suggests the user that originally authenticated the connector may have changed the password or the session may have been invalidated. In this case, re-authenticating the Facebook Marketing source connector should allow the next sync to succeed.

Accessing Logs

However, sometimes the "Failure Origin" message does not provide enough additional context into the error to troubleshoot the problem and you may need to view the full sync log for more information.


You can access the logs for a particular sync in the UI by clicking the three dot menu button on the right side of the sync job and either selecting "View logs" to view and search the logs within the UI or "Download logs" to download and open the logs in a text-viewer of your choice.

Syncs will normally make three attempts to succeed and logs are separated between the attempts. In the downloaded file, the attempts are separated by a `>> ATTEMPT 1/3` line.

In the UI, you can view the logs for each attempt by using the dropdown on the left side of the search bar.

Screen Shot 2023-07-18 at 1.53.32 PM.png

Reading and Analyzing Logs

Logs are chronological from top to bottom. Each log entry represents a single event or message and usually contains several key pieces of information:

2023-07-11 17:23:40 source > Read 5 records from payment_intents stream
  1. Timestamp: The date and time the event occurred in UTC

  2. Source/Logger: The place where the event occurred (usually "source", "destination", "replication-orchestrator" or "normalization"

  3. Message: A detailed description of the event, including error codes or relevant data.

When searching through logs for errors, keep an eye out for keywords like "exception", "error", and "fail" or specific error codes that could provide more information.

Was this article helpful?
3 out of 5 found this helpful



Please sign in to leave a comment.

Articles in this section