/debugging-executions

name: debugging-executions
description: >-
  Debug failed or wrong-output workflow executions using executions tools. Load
  when the user reports execution failures, unexpected node output, empty
  parameter values after a successful run, or a node showing a red or failed
  expression error. Also load when a live run you started for the user fails
  with an error from a node or an external service (for example a 401), before
  you explain the cause to the user.
recommended_tool_groups:
  - executions
  - workflows

Debugging Executions

Use this skill when debugging workflow execution failures or successful runs with wrong or empty values.

When the user reports it still fails

Re-run the failing path by running `run_workflow` (or `workflow_builder_verify_built_workflow`) through `call_tool`, and inspect the real result before responding. Do not restate that the workflow is "fixed", "verified", or "working", and do not attribute the reported failure to a test-harness artifact, stale state, or "it works in production" without a re-run against the failing path. Treat live signals as real: an execution error, partial coverage (`nodesNotReached`), an empty node, or a missing node is a real defect to investigate, not something to explain away. If you genuinely cannot re-run the failing path, say so plainly and name what is unconfirmed instead of repeating a success claim.

Before you name a cause

Say what you checked before you say why it failed. Do not lead with a cause that you did not check. A plausible guess presented first reads as a finding, and the user acts on it.

Check what you can see on the n8n side first. These checks are read-only, so run them unprompted:

• **Auth errors (401, 403, "unauthorized", "invalid key").** Confirm that the

credential exists (`list_credentials`, with `ids` for a specific credential), that the node uses it (the node's `credentials` in `get_workflow`; resolved parameters show only the auth type, not which credential is bound), and what `test_credential` reports. A generic credential, such as Header Auth, can pass its test without a call to the service, so a pass does not show that the service accepts it. Say so when you report the check.

• **Other node errors.** Start from `debug_execution` and the

resolved parameters of the failed node.

Then report the checks and their results, and only after that give a cause. You cannot read a stored secret, so a cause about its format or value is a hypothesis: label it as one, and say which check would confirm it. Do not blame the user's account, billing, credit, plan, or quota unless the error says so.

A cause outside the workflow does not mean that the workflow is correct. Before you say that the workflow is wired or configured correctly, read the expression parameters of every node on the failing path, not only the node that failed. An expression that reads the wrong field, or a literal placeholder where an expression belongs, is a defect even when a different error stopped the run. Report each defect separately from the cause of the failed run.

Draft versus live

A published workflow runs the version that was published, not the draft you edit. Your save creates a draft, and the draft is not live until somebody publishes it. So a fix to a live workflow changes nothing in production on its own.

Two consequences when the user reports a live workflow failing:

• **Read the version each execution ran.** `list_executions( workflowId)`

returns `workflowVersionId` on every row, plus `workflow.activeVersionId` (the published version) and `workflow.draftVersionId`. Only a row whose `workflowVersionId` equals `workflow.activeVersionId` ran the published code. A run of a draft proves nothing about production. A `workflow.draftVersionId` different from `workflow.activeVersionId` means the latest changes, including any fix you just made, are not live.

• **Name the version when you invite a retest.** Say whether the user tests the

draft or the published version. "Try it again" after a draft-only fix sends the user to the broken published version, and the fix looks like it failed.

Do not report a fix as live until the published version is the fixed one. Ask whether to publish it instead. After a publish, a new live run is what confirms the fix — an earlier execution ran the old version.

Testing event-triggered workflows

Run `run_workflow` through `call_tool` with `inputData` matching the trigger's output shape — do not rebuild the workflow with a Manual Trigger. For trigger `inputData` shapes, read the workspace file `knowledge-base/reference/trigger-input-data-shapes.md` when a sandbox workspace is available.

The run the user is looking at

A message about a failed run often names its execution, for example "currently viewing its execution `<id>`". Read that execution by its id. Do not pick a run by running `list_executions` through `call_tool` instead: `list_executions` can return an older run, and it does not show a manual run that n8n did not save.

When saving manual executions is turned off, n8n can keep a finished manual run for a short time, only for the user who ran it. You act as that user, so you can read it by its id in that time. When the id is not found, tell the user that you cannot read that run. Ask the user to run it again, or offer to run it yourself: n8n saves every run you start. A new run repeats what its nodes do, so check for write nodes first (see below).

Failed execution

`debug_execution` already includes `failedNode.resolvedParameters` — start there. That bundle has `parameters` (raw, with expressions intact), `resolved` (substituted), `failedExpressions` (those that threw), and `emptyResolutions` (those that resolved to `null`/`undefined`/`""` silently). The offending expression is usually visible without a follow-up call. Entries in either list tagged with `reason: "unreconstructable-context"` are NOT real bugs — they reference