Resolving an individual error gets one record unstuck. Finding the root cause keeps the same error from coming back. This article covers why root cause analysis is worth the extra time and gives an overview of the diagnostic tools available for investigating errors more deeply. For errors integrator.io resolves automatically, see How automatic error resolution works. For developer techniques to automate handling once you understand a root cause, see Automate error handling with custom hooks.
Why root cause analysis matters
Most runtime errors come from a data quality issue in the records you're importing — keeping source and destination data clean, accurate, and current directly improves how reliably your flow runs. When an error occurs, it's tempting to fix that one record and move on. But if the same condition produces the error again on the next run, you're back where you started.
For any error integrator.io can't auto-resolve, take the time to understand what went wrong between the two systems and whether your flow's logic contributed to it — not just to close the immediate error, but to prevent the same or a similar one on the next run. If you need a specific record processed urgently, it's fine to use the retry data to fix that record right away — just make sure the root cause analysis still happens afterward.
Root cause analysis works best as a shared responsibility. IT and the admins of the applications you're integrating both need enough access to investigate. The application admins — who know the data and the destination system best — are typically best placed to lead the analysis, with IT as an escalation point if the problem persists.
Most errors trace back to changes in the source or destination application, whether from a vendor update or a change someone on your team made. A company-wide change management process for these systems can prevent a meaningful share of errors before they happen.
Diagnostic tools
Your approach to investigating an error can draw on one or more of these tools — tailor it to your use case rather than working through every one every time.
| Tool | What it's for |
|---|---|
| Error fields | The Fields tab in Error details shows where (source) and when (timestamp) the error occurred, and which record it affected if you've set the trace key. The classification hints at possible causes. Edit the retry data and retry to test a fix — if it worked, the error won't reappear in Open errors. Celigo Ora can analyze the error and suggest next steps. See Understand the Errors page, Error classifications, and Error management with Celigo Ora. |
| Execution logs (run logs) | Give step-level status and timing for each stage of a flow run, when you need per-record visibility into how a flow executed. In Flow builder, go to Run history, select the Run logs icon next to a flow step, then use Trace view to follow a single record end to end. |
| Diagnostics | Download diagnostics as a ZIP file from the Run console or Run history. Alongside export and import flow information, it includes parent job, child job, and job error details — useful for sharing a configuration with someone else or examining it yourself. |
| Audit logs | A record of every change any user made to an integration's resources, retained for a year. If a flow that had been running cleanly develops a new error, check the audit log around that time to see whether a change caused it. See View or download your audit logs. |
| Developer playground and Advanced Field Editors (AFEs) | Perform real-time syntax checking for JavaScript and Handlebars. Use when an error points to a script in a hook, filter, or mapping: launch the advanced field editor on the relevant step, or open the playground, and paste the script to see syntax errors inline. |
| Integration and flow analytics | Charts of errors, successes, ignores, and average processing time over time, useful for spotting trends and forecasting flow health. See Monitor errors in flow runs. |
| Debug logs (HTTP connectors) | Show the request and response traffic between integrator.io and a flow step's endpoint, including details useful for troubleshooting — for example, verifying what a pre-save page hook actually did to a record. Open them from a connection's Actions > Debug connection, or select View debug logs in the step editor header. See Debug flow steps and Debug a connection. |
| Run console and Run history | The Run console shows details of flows currently running; Run history lists previous runs, including error counts and retry details. The error count shown here reflects errors at the time of the run and isn't updated afterward — check the flow step, integration Flows tab, or dashboards for the current count after retries. See Monitor errors in flow runs. |
| Dashboard | The account and integration dashboards give a quick breakdown of errors with run details for the past 30 days or your custom data retention period. Select a flow's Run number to open Run history at the flow and flow-step level. See Monitor errors in flow runs. |
| Runtime script debugging | Console statements you can add anywhere a JavaScript export or import hook runs, to inspect the shape and content of data as it flows through a step. View the output in the script's Execution log: go to Resources |
| Import preview panels | Test API calls to HTTP-based connectors directly in integrator.io using mock data: see the request integrator.io would send, and send a sample record to see the destination's actual response. In the step editor, use the Input, Preview, and Mock response tabs, then select Preview request and Send to see the Request, Response, and Parsed output. |
| Integration Lifecycle Management (Revisions) | Back up working custom integrations, compare revisions, and revert to a specific one if a change causes problems. Find it on the integration's Revisions tab (More > Revisions), where you can create a pull, create a snapshot, or ignore fields during a pull. Revert is an action on a revision. If you have non-production environments, develop and test changes there before promoting them to production. |
In a custom flow, two settings make errors easier to read before you start diagnosing them. Overriding the trace key lets you build a more identifiable value from several attributes — an internal ID plus a vendor name, for example — which then shows in the Trace key column and at the top of the error details. Setting Data URI template on an export or import turns the error into a user-friendly link back to the record in the source or destination system. See Set a custom trace key to uniquely identify a record.