Name: troubleshooting-flows
Author: celigo

Diagnose and resolve Celigo flow failures -- total failures, partial errors, stuck jobs, empty runs, and performance issues. Use when a flow is failing, producing errors, returning no data, or running slowly.

<! TIER:1 Troubleshooting Flows A flow is broken when it fails to move data correctly. This skill covers systematic diagnosis: identifying the problem type, isolating the failing step, inspecting errors, and resolving them. Troubleshooting concerns: Job status understanding what completed , failed , canceled , and retrying mean for the flow Error analysis grouping errors by pattern to find root causes instead of reading them one by one Request/response inspection seeing exactly what was sent and returned at each step Execution logs record level tracing through every stage of the pipeline Retry and resolution fixing error data and retrying vs bulk resolving Delta/state issues lastExportDateTime drift, stuck deltas, re processing windows How to Run the Steps This skill names each diagnostic step by what it reads or changes; the exact calls depend on how you reach the account. Read the one reference that matches your tools both follow the step numbers of the Diagnostic Workflow below: Celigo MCP tools ( list flow runs , list flow errors , triage flow errors , ...) [references/mcp.md](references/mcp.md) The celigo CLI [references/cli.md](references/cli.md) Diagnosis is read only. Retrying errors, resolving them, running a flow, and changing configuration all write to the account or to the connected systems do them only when the user asked for the fix, not as part of finding the cause. Read Before You Answer A diagnosis rests on what this account shows, not on what usually goes wrong. Work through these in order and stop only when the evidence names a cause: 1. Pin down what the user means. Which flow or integration, and which symptom: a failed run, some records failing, nothing exported, a stuck or late run, wrong data with no errors, or "it used to work". For "the most recent error", compare the errors' times, not which step has the most errors. If the user only says things are slow and no flow's recent runs are slower than its own history, ask one question which flow, run, screen or call is slow rather than tuning anything or reporting that nothing is slow. 2. Read the run. The latest run's status and each step's counts (success, error, ignore, pages). They name the [problem category]( problem categories) and the step to look at. 3. Read the errors themselves. Open the failing step's errors: message, code, source , classification , and the values one or two failing records carry (their retry data). Group them by message. Quote what the errors say "the lookup has no entry for 'Local Pickup'", not "a lookup probably failed". 4. Read the configuration the errors point at. The mapping row, lookup, request body or URI, filter, query, hook or connection the error names. A cause has to explain why these records failed while others on the same step succeeded. Some settings act only in one mode an export's once callback only when its type is once , its {{lastExportDateTime}} tokens only when it is delta so read the type before naming such a setting as the safeguard or the cause. When the user calls it a platform bug, read the configuration before agreeing or filing anything. 5. If it used to work, read what changed. The audit log of the step, the flow and the step's connection, just before the first error or slowdown: a connection change (concurrency, auth, auto recover) explains a failure or a slowdown as often as a step change. 6. Before advising a retry or a re run, say what it will do. A retry runs each failed record's saved data through the step as the step is now, so it fails the same way until the configuration or that data is fixed. A re run after a canceled or failed run reads the same window again, so a create only import writes again the records it already wrote. An empty delta run leaves the checkpoint where it was, so the first run after the fix picks those records up no backfill run is needed. When the user asks for a retry that would write records a second time errors a postSubmit hook raised after the destination accepted the records, or creates that timed out say so and ask before retrying. 7. Answer with the evidence. Name the cause as a specific field, value or setting, list the reads that show it, give the fix, and say what not to do yet. An ignored record leaves no error and no retry data, so once its cause is fixed it comes through only if the source sends it again. When some records fail (or are ignored) and others go through, say what those records carry that the others don't the value, character or missing field in their data. Change nothing the user didn't ask you to change: when they ask you to fix it, make the change; when they ask why or how to fix it, say what to change and offer to make it. Either way, a retry, a run or a resolve waits for their go ahead. Problem Categories Total Failure Job status is failed with 0 successful records. The entire run collapsed before processing any data. Typically numPagesGenerated: 0 (export level failure) or pages generated but numPagesProcessed: 0 (import level failure on the first page). Common causes: connection failure (credentials expired, endpoint down), export query error (invalid SQL, bad saved search ID), missing/deleted resource, permission denied. Partial Failure Job status is completed but numError 0 alongside successful records. Some records failed while others processed normally. The failed share varies widely, from a handful of records to a large part of the run. Common causes: validation errors on the destination (required fields missing, type mismatches), duplicate key violations, record level lookup failures, rate limiting on specific batches, data dependent issues (specific records have bad data). Empty Run Job completes successfully with 0 errors AND 0 records processed. Common causes: wrong resourcePath on the export (extracts from wrong JSON path), delta export with no changes since last run (legitimate), output filter too restrictive (all records filtered out), source query returns no results, webhook export with no inbound events, or the export now reads another source its connectionId was switched to a different connection (a dev or sandbox store, another account). The export's audit log shows the switch; its old value names the connection the export read before, the one to point it back to if the switch was a mistake. On a file export, also check its name filters ( fileNameStartsWith , fileNameEndsWith ): a file whose name doesn't match is skipped silently, and the match is case sensitive on most servers, so ORDER skips order 123.csv . A filter changed in the export's audit log around when the runs went empty is the likely cause; its old value is the one to set back. A delta run that exports nothing leaves the checkpoint where it was, so once the cause is fixed, the next run picks up the records the empty runs missed no backfill run is needed. An empty execution log proves nothing here: the log holds one entry per record, so a run that exported nothing has none at any log mode. Stuck or Long Running Job stays in running or retrying status longer than expected. Common causes: large dataset with no pagination limits, destination system slow to respond, script hook with long running logic, on premise agent connectivity issues, rate limiting causing backoff. A run that got slower. Compare the slow runs with earlier runs of the same flow ([Monitoring Lenses]( monitoring lenses and execution metrics)). In a slow run's family, each step's child job has its own startedAt and endedAt ; the step whose child job ends long after the others is the one holding the run. Before blaming a change, compare that step's records per run with its time per record: more records at the same pace is volume, not a fault. Then check what sets that step's pace: its connection's concurrency ( targetConcurrencyLevel while auto recover is on) against what the target system allows, rate limit errors on that connection, and whether the step calls the target once per record a lookup step does, as does an import's dynamic lookup where a lookup cache answers from stored values instead ([configuring lookup caches](../configuring lookup caches/SKILL.md)). Answer with those numbers for the slow run and a normal one: each step's time, its records per run and its time per record or per call. Recommend the change that shortens the slow step, and leave out tuning for the steps that aren't holding the run, such as a larger page size on an export that takes one minute of a twenty minute run. Intermittent Failures Flow sometimes succeeds and sometimes fails with the same configuration. Common causes: token/session expiry mid run (long running flows), rate limiting (varies with concurrent flows), transient network errors, source system maintenance windows. Error Diagnosis Framework Classification The platform stamps each error with a read only classification read it from the error itself (every error in a step's error list carries it) rather than guessing from the message or status code. The classifier is heuristic, so identical messages can classify differently, and nothing you configure changes a classification. It decides whether the platform recovers on its own: Classification Typical cause Recovers on its own? Action intermittent Timeouts, 5xx responses, dropped connections Yes up to four automatic retries, the first about 30 minutes after the error, while the flow's autoResolveMatchingTraceKeys is on (the default). A retryAt on the error means it's still in auto retry Wait. Once attempts are exhausted (no retryAt ) or the setting is off, retry manually when the target is healthy. A timed out create may have been written anyway, and every retry, automatic or manual, sends it again: for a create only import, check the destination or make the import skip records that already exist (configuring imports) rate limit HTTP 429, quota exceeded Through the connection, not the error list with auto recover on, rate limited records are held while concurrency drops and climbs back, so the flow can look stuck with no new errors Open rate limit errors mean auto recover is off or gave up: re enable it or lower targetConcurrencyLevel (see configuring connections), then retry connection Credentials, permissions, expired token, offline connection No and these errors carry no retry data Fix the connection (ping it, or read its offline flag), then re run the flow value The destination rejected a value (format, status transition, locked field) No Fix the mapping (retrying an import's error runs the fixed import) or, when the record itself is bad, edit its retry data; then retry missing A required field or referenced record is missing No Supply the data or fix the lookup or mapping, then retry duplicate The destination already holds the record No Fix the match or upsert criteria; resolve the error if the existing record is right. A resolve drops the refused record, changes included: when they should reach the destination (an insert refused on a unique key), make the import update or upsert, then retry parse Malformed JSON or XML, Handlebars or script syntax or a template naming a field the record doesn't have ( "<field " not defined in the model ), which is missing data, not syntax No Fix the template or script, then retry. For a field "not defined in the model", read the record's retry data first: fix the data, or the import's handling of records that lack it too large Request, response, or page too big No never auto recovered Reduce page or batch size, or trim the payload, then retry (none) Nothing classified with confidence No Read the error's code and message and its raw HTTP request/response, then investiga