--- name: celigo-flow-failure-diagnosis description: Diagnose why one specific Celigo flow or flow run failed, working from its runs, execution logs and flow errors to a root cause with evidence, rather than surveying the whole account. Use when the user names a flow, shares a run or job, or asks why a particular integration failed last night, stopped syncing or keeps erroring. --- # Diagnose one Celigo flow failure The goal is a **root cause with evidence** for one flow. The error text is the symptom. The cause is why this flow failed on this run, with this input, after this change. Do not survey the whole account here; that is the job of the health audit. Stay on the one flow until it is explained or you have shown what is missing. ## 1. Pin down the flow and the failing run Confirm which account and environment you are reading before anything else. A flow name can exist in several environments. If the user has not said, ask. Use `list_flows` to find the flow by name or id, then `list_flow_runs` for that flow, newest first. Identify: - **The most recent failed run**, and whether earlier runs succeeded. A flow that failed on the first run after a change is a different case from one that has failed every run for weeks. - **The last successful run** and the time between the two. That window is where the cause usually sits. - **Whether the latest run is still in progress.** A run that is still going is not yet a failure; wait for it to finish before concluding. State the failing run id and its time. Everything after this uses that run. ## 2. Read the run's own logs before the error list Use `list_execution_logs` for the failing run. Logs show the order of events: which step ran, which step first went wrong, and what happened just before. The first failing step matters more than the last one. A later step that fails because an earlier step produced nothing is downstream of that earlier step. Look for: - **The first error line**, not the summary. Summaries repeat the final symptom. - **Steps that ran but processed zero records.** Silent empty runs are a common cause of "it succeeded but nothing arrived". - **Timing.** A timeout or cut-off partway through often points to volume, not logic. ## 3. Match the error to the flow errors Use `list_flow_errors` for the same flow and time window to see the per-record errors the run recorded. Group them before reading them one by one: - **Same message repeated across many records:** one cause, probably a mapping, lookup or reference problem. Fix it once. - **Different messages for different records:** check whether they share a field, a record type or a value pattern (empty field, unexpected format, a value the destination rejects). - **A single record failing:** usually bad source data. Confirm with the record's fields before blaming the flow. Use `get_flow_error_retry_data` only to read what a retry would send. Do not retry from this skill. ## 4. Compare with what changed Failures usually follow a change. Check the timeline: - **Did this flow's failures start at a particular run?** Compare the first failing run with the last good one. - **Did the source or destination change?** Ask the user about recent edits on either system. Account-side edits show up in the audit trail; if the cause is unclear, say that the audit log review is the next step. - **Did an upstream dependency change?** Check `list_connections` for a connection that is offline, expired or pointing at a different account. Do not assert that a change caused the failure until you can show the failure begins at the change. ## 5. Form the hypothesis and try to break it State it as: "This flow fails at **step X** because **A**, when **B**, starting at **run Y**." Then look for one fact that would disprove it: the same error on an earlier successful run with the same data, or failures that do not match the proposed input. Confidence is high only when you have the failing step, the triggering data pattern and the run where it started. Medium if you have the step and the error but not the data. Low if you only have the error text. ## 6. Propose the fix, and stop before changing anything Fix the cause, not the symptom. A mapping that drops a required field should be fixed in the mapping, not by ignoring the error. Say what the fix is and how to verify it: the next run should clear the error group you identified. Any change to the flow, its connections or its mappings, and any retry or re-run of a failed run, is a write. Describe it and then wait for the user's explicit yes. Do not start a run to test the hypothesis. ## Common patterns and traps - **Failed on the first run after a deploy or edit:** the edit is the prime suspect. Compare the flow's configuration with the last good run before blaming the external system. - **Every run fails, the same step every time:** a configuration or credential problem, usually a connection or a lookup, not the data. - **Runs succeed but records are missing:** a filter or a cut-off condition is excluding them. The run logs will show zero or low counts at the step. - **Errors only for some records:** check the failing records for a shared field value, empty field or unusual format rather than reading the flow logic. - **Permission errors from list or read calls:** the signed-in user or token lacks access. Say so and stop; do not work around it. - **Confusing a failed run with a failed flow:** a flow can have one bad run and be healthy now. Check the latest run before reporting the flow as broken. - **Trusting the summary line:** read the first error in the logs, not the final one. ## Output ``` Flow: (), run at