debug-execution

---
name: debug-execution
description: "Diagnose an n8n workflow that failed, produced the wrong result, or stopped running, working from execution data rather than the workflow definition. Use when the user reports a broken, failing, or flaky workflow, asks why a run failed, or asks what changed. Triggers: my n8n workflow failed, why did this workflow break, n8n execution error, workflow stopped working, debug this workflow, intermittent failures."
compatibility: Requires Kiro with Agent Plugins support and n8n 2.34.0 or later with execution read access.
metadata:
  author: n8n
  version: "1.0.0"
---

# Debugging a failed n8n workflow

Use this when a workflow failed, produced the wrong result, or stopped running.
Work from evidence. Do not guess from the workflow definition alone.
Apply the [connect-n8n pre-flight](../connect-n8n/SKILL.md) before the first n8n
tool call in a conversation. Use the schemas the server actually lists.
Keep investigation and repair on the native connection selected by that
preflight. Resolve an ambiguous instance before reading or changing a workflow.

## Order of investigation

1. **Find the relevant run.** Use the execution the user identified, or search
   with `search_workflow_executions` for the workflow and reported time. For an
   execution error, filter to failures. For incorrect output, include successful
   runs too. If the workflow stopped running, check when it last ran; do not
   substitute an unrelated old failure. Note whether the problem is constant or
   intermittent.
2. **Open it.** Call `get_workflow_execution` with `includeData: true` to read
   node results; the default response contains metadata only. Use `nodeNames`
   and `truncateData` when useful to limit the returned data. Find the first
   node that failed, not the last. Later errors are usually consequences.
3. **Read the input to the failing node**, not only its error. Compare the actual
   fields and values with what the node expects before diagnosing a shape mismatch.
4. **Compare against the version that ran.** Inspect the workflow definition
   saved with the execution when available. `get_workflow_details` describes
   the current draft and published version, which may differ from the failed
   run. Use version history to resolve the difference before editing.
5. **Check whether it changed.** If it used to work, `get_workflow_history` and
   `get_workflow_versions_diff` show what was edited and when. Match that against
   the date failures started.

## Common causes

- **Missing input.** Check whether the upstream node emitted items and whether
  those items contain the expected fields. A node receiving no items may not run.
- **Shape change.** An upstream API changed its response. The execution data shows
  the real payload; compare it against what the expression expects.
- **Credential expired or revoked.** The error is an auth failure from the
  external service, not from n8n. The user has to fix the credential; you cannot.
- **Rate limit or timeout.** Look for a 429, a socket error, or evidence of a
  service limit. Check whether retrying could duplicate a write before adding
  retry behavior.
- **A change that was never tested.** The history diff shows an edit right before
  the first failure.

## Reporting

Say three things, in this order:

1. Which node failed and what the error was.
2. Why, in terms of the actual input data you read.
3. The fix, and whether it is something you can apply or something the user has to
   do.

Do not propose a fix you have not grounded in execution data. "It might be the
credential" is not a diagnosis when you can read the error.

## Fixing

- Read `update_workflow`'s advertised input schema before constructing operations.
  Its operation and node objects are not Workflow SDK factory calls. If Kiro
  truncates tool discovery, inspect its saved response. Kiro 1.1.70's old bundled
  power path omits nested schemas entirely; its saved response cannot recover those
  fields. Report this [client limitation](../../docs/setup-helper.md#troubleshooting)
  before editing if the operation schema is unavailable. Do not infer field
  names from SDK code or an error message.
- Apply the grounded fix with `update_workflow`. Inspect validation warnings.
  Before any test, apply the [build-workflow test checks](../build-workflow/SKILL.md#test-before-you-claim-it-works):
  prepare pin data, inspect which nodes remain unpinned, and obtain authorization
  for their I/O or state changes unless already authorized. Unpinned command,
  file, and Code nodes can execute on the n8n host during `test_workflow`.
- Run `test_workflow` and read its result. Report which nodes were simulated.
  A pinned HTTP or credentialed node cannot prove an API, auth, connectivity,
  or rate-limit failure is fixed. If a real check is needed, explain its effects
  and use an authorized `execute_workflow` call with an explicit execution mode.
  Read the final execution result; otherwise leave the integration unverified.
- For failures that are safe to retry, prefer an `update_workflow` call with a
  `setNodeSettings` operation setting `retryOnFail` and
  `maxTries` over restructuring the workflow.
- If the fix needs error handling the workflow does not have, explain the options
  and ask. Do not add an Error Trigger or an error workflow silently.
- Report whether the change is in the draft or the published version. A passing
  draft test does not update the production workflow. Publish only if the user
  authorized it, then verify the relevant published behavior. Check live effects
  before changing workflow-level settings, which can reactivate a published
  workflow.

## Limits

- Agent conversations are not workflow executions. `get_workflow_execution` and
  `search_workflow_executions` cover workflow runs only, including workflows an
  Agent called as a tool.
- Execution data is retained according to the instance settings. If the run you
  want is gone, say so rather than reasoning about a run you cannot see.
- If tools or workflow data are unavailable, use
  [connect-n8n](../connect-n8n/SKILL.md) to distinguish version or feature limits,
  OAuth permissions, workflow exposure, and user access. Do not diagnose a
  failure from a definition when the necessary execution evidence is missing.

From n8n-io/n8n-kiro-power at 782ab71, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md6.3 KB · 40f99d2adbda

1 file, 6.3 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.