Flow Debugging

Audience: Everyone · Tags: flow, debug, failure, explain

Purpose. When a run doesn't succeed, you shouldn't have to guess why. The Flow Debugger gives you a read-only, plain-English answer: what failed, what error code it hit, and what to do about it. It only reads what the execution engine already recorded — it can't change a run.

Two ways to read a failure

	Flow Debugger (/flow-designer/debug/:runId)	Snap Studio's explanation (/flow-designer/studio/runs/:runId/explain)
Audience	Anyone comfortable with a bit of structure (status codes, step numbers)	Fully plain-English, no jargon — a headline sentence plus per-step detail
Extra fields	connectorInvocations, retries, failureCause, suggestedFix	headline, ordered steps with friendly status words, a problem: { message, suggestion } if it failed
Where it's used	The general run-detail view	The Snap Studio result screen after Save & test

Both are built on the same underlying run data — pick whichever reads better for the moment. Studio's version is reachable for any run, not just ones Studio built.

The full failure taxonomy

Every step failure carries one of these errorCode values:

Code	Plain meaning	Suggested fix
auth	The credential is missing, expired, or invalid	Re-connect the connector — its credential is missing, expired, or invalid.
rate_limit	The app throttled the request	The provider rate-limited the request. Reduce frequency or add a retry/backoff policy.
timeout	The app was too slow to respond	The provider was slow. Increase the timeout or retry with backoff.
upstream_5xx	The app had a server error on its side	The provider returned a server error. Retry later; check the provider's status page.
bad_request	The action's inputs were wrong or malformed	Check the action inputs — a required field is missing or malformed.
blocked	The destination URL was blocked by SSRF protection	The destination URL was blocked by SSRF protection. Use a public https endpoint.
unknown	Unexpected — doesn't fit the above	An unexpected error occurred. Inspect the step details and connector logs.

These same codes are what you filter runs by (GET /runs?errorCode=...) and what missing_credential in flow validation helps you avoid before a run ever happens.

Worked example: a failing run

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flow-designer/debug/run_00a11b22c33d \
  -H "Authorization: Bearer $TOKEN"

{ "data": {
  "runId": "run_00a11b22c33d",
  "status": "failed",
  "attempts": 1,
  "timeline": [ "..." ],
  "steps": [
    { "id": "step_1", "stepNumber": 1, "stepType": "action", "connectorKey": "slack",
      "actionType": "send_message", "status": "failed", "attempt": 1,
      "errorCode": "auth", "failureReason": "Slack credential invalid or expired." }
  ],
  "retries": [],
  "connectorInvocations": [
    { "stepNumber": 1, "connectorKey": "slack", "capability": "send_message", "status": "failed", "attempt": 1, "errorCode": "auth" }
  ],
  "failureCause": "slack.send_message: auth",
  "suggestedFix": "Re-connect the connector — its credential is missing, expired, or invalid."
} }

The plain-English version of the same run, from Snap Studio's explain endpoint:

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flow-designer/studio/runs/run_00a11b22c33d/explain \
  -H "Authorization: Bearer $TOKEN"

{ "data": {
  "runId": "run_00a11b22c33d",
  "status": "failed",
  "headline": "Your flow ran, but step 1 hit a problem.",
  "steps": [
    { "title": "Step 1 — slack: send message", "status": "failed",
      "detail": "This step failed because it couldn't sign in — a credential or setting (like SMTP for email) is missing or wrong." }
  ],
  "problem": {
    "message": "Slack did not work: it couldn't sign in — a credential or setting (like SMTP for email) is missing or wrong.",
    "suggestion": "Re-connect the connector — its credential is missing, expired, or invalid."
  }
} }

A successful run's headline reads "Success — your flow ran from start to finish." instead.

Step-by-step

1. Open the run (from Monitoring Runs or a webhook response's runId).
2. Call /flow-designer/debug/:runId (or the Studio /explain variant for the friendlier read).
3. Match the failed step's errorCode to the table above and apply the fix.
4. Re-trigger the flow — either resend the original event, or POST /executions/:id/retry on the failed run (this creates a new run).

Best practices

• Start every investigation here before digging into raw events — failureCause and suggestedFix answer most questions immediately.
• If several runs share the same errorCode, look for a systemic cause (an expired credential affecting every run, not just one) rather than treating each as isolated.
• Bookmark the errorCode → fix table above; it's the fastest troubleshooting shortcut in the product.

FAQ

Can I see the actual data that was sent? No — the debugger shows metadata and sanitized status only; request/response bodies and secrets are never stored (see Security). Does debugging affect the run? No, it's strictly read-only. Can I retry from here? Yes — POST /executions/:id/retry starts a fresh run using the same flow version.

If something goes wrong

For connector-specific failure patterns and fixes beyond this guide, see Connector failed.

---

Related: Execution History · Monitoring Runs · AI Flow Drafting