How to Debug Failed n8n Workflows: Step-by-Step Guide

Most n8n failures are not mysterious. They repeat the same patterns: a credential expired, an expression pointed to the wrong field, a webhook URL was the test one instead of the production one. The hard part is knowing where to start when all you see is a red node and a generic error message.

This guide walks through the tools n8n gives you for debugging, the five errors that cover most real-world failures, and two nodes that help you handle failures more intentionally going forward.

1. Start with Execution History

Every time a workflow runs, n8n records the execution: what data came in, what each node did, and where it stopped. This is the first place to go after a failure.

Open the workflow and select the Executions tab at the top. You will see a list of past runs with their status: Success, Failed, or Waiting. Select a failed one to open it.

Inside the execution view you can see the canvas in its failed state: the node that caused the failure is marked in red, and the bottom panel shows the error message and the log. This tells you which node broke and what the error was, before you touch anything.

Read the error message before doing anything else. Many failures explain themselves: "401 Unauthorized", "Cannot read properties of undefined", "The provided authorization grant is invalid". The node name plus the error text is usually enough to know what went wrong.

2. Debug in Editor: reload real data and rerun

Once you understand what failed, use the Debug in editor button. This loads the actual input data from the failed execution into your current canvas. You can then make changes to the broken node and rerun the workflow using the same real data, without needing to trigger a new event.

This is especially useful for workflows triggered by external events: a form submission, a webhook call, or an email. Reproducing that exact input manually takes time. Debug in Editor gives you the original payload immediately.

For successful executions, the same panel offers Copy to editor instead. That is useful when you want to test changes against a known-good input rather than a failed one.

3. The 5 most common errors

These five patterns account for most of the failures you will actually see in production n8n workflows.

Credential or auth error (401, 403)

The node could not authenticate with the external service. Common causes: the credential expired, the API key was regenerated, OAuth tokens were revoked, or the connected account lost the required permissions.

Fix: open the node settings and re-test the credential. If it fails the test, reconnect or regenerate it in the credentials panel. For OAuth-based services like Gmail or Google Sheets, you may need to re-authorize from scratch.

A 403 is slightly different: the credential is valid but the account does not have permission to perform that specific action. Check the API scopes or the account's role in the connected service.

Expression error (undefined, wrong syntax)

An expression in a field is referencing a value that does not exist. The result shows [undefined] or the workflow throws a "Cannot read properties of undefined" error.

Fix: click on the broken field to open the expression editor. On the left panel, expand the input data from the previous node and check the actual field names and structure. A common mistake is using {{ $json.name }} when the real field is nested: {{ $json.contact.name }}. Use the field browser to drag the correct path into the expression.

Webhook not firing (test URL vs production URL)

The workflow is active, the external service is configured, but no data arrives. This is almost always a test URL vs production URL mismatch.

n8n gives each webhook two URLs: one for testing (only works while the workflow is open in the editor), and one for production (only works when the workflow is active). If you configured your external service with the test URL and then activated the workflow, nothing will arrive because the test URL stops listening once you close the editor.

Both URLs are visible directly inside the Webhook node settings. Many people only notice the first one. The test URL is shown at the top; the production URL is listed below it. Copy the production URL and update it in the external service, then test by triggering the actual event from that service.

API timeout or rate limit (429, execution stops around 30 seconds)

The HTTP Request node or an API-connected node stops responding. You may see a 429 Too Many Requests error, or the execution simply times out.

n8n's default HTTP Request node timeout is 5 minutes (300,000 ms), but many workflows hit limits earlier because the external API enforces its own rate limits or because a slow response blocks the execution. A 429 means you are sending too many requests too fast.

Fix for rate limits: add a Wait node between batched requests to slow down the pace. Fix for timeouts: check whether the external API is responding at all (test it directly in a browser or with a manual HTTP call), then increase the timeout in the HTTP Request node settings if the service is just slow.

Data type mismatch (array vs object, null values)

A node expects a single object but receives an array, or a field contains null and the next expression tries to read a property from it. This often surfaces as "Cannot read properties of null" or unexpected behavior where only the first item is processed.

Fix: use the Input panel to inspect what the previous node actually returned. If it returned an array when you expected an object, add a Split Out node to break it into individual items before processing. If null values cause crashes, add an IF node upstream to filter them out before they reach the sensitive step.

4. Enable debug logging (self-hosted only)

If you run n8n on a VPS and the execution log does not give enough detail, you can turn on verbose logging by setting N8N_LOG_LEVEL=debug in your .env file and restarting the container.

N8N_LOG_LEVEL=debug

With debug logging active, the server logs include detailed HTTP request and response data, credential resolution steps, and node input/output at each stage. This is useful for intermittent failures that are hard to reproduce by opening the editor: connection timeouts, credential handshake errors, and SSL issues tend to surface in the logs before they appear clearly in the execution view.

5. The Debug Helper node

Most n8n users do not know this node exists. The Debug Helper is a built-in utility node that lets you deliberately trigger different error types or generate random test data inside a workflow.

The four modes are:

• Do Nothing: passes through without doing anything. Useful as a placeholder.
• Throw Error: deliberately fails the workflow with a message you specify. Use this to test your error handling before a real failure happens.
• Out Of Memory: generates a large memory allocation to simulate an out-of-memory error. Useful for stress-testing self-hosted setups.
• Generate Random Data: produces random structured data. Useful when you need test input but do not have a real event to trigger the workflow.

The most practical use of Debug Helper for most workflows: add it temporarily before your error-handling path and set it to Throw Error. This lets you verify that your Error Workflow actually fires and sends the alert before you see a real failure in production.

6. Stop And Error: controlled failures with clear messages

Sometimes a workflow should stop not because something broke unexpectedly, but because the data does not meet a condition you care about. An empty response from an API, a missing required field, a contact that should not be there. Without explicit handling, the workflow either completes silently or fails with a confusing message.

The Stop And Error node ends the workflow at that point and marks the execution as failed, with the message you provide. Two error types are available: Error Message (a plain text string) or Error Object (a JSON object with structured error properties).

Used with an IF node upstream, this gives you intentional failure points. The workflow says "no valid email found, stopping here" instead of crashing three nodes later with a cryptic null reference. When that controlled failure triggers your error alert, the message is already readable.

Stop And Error can only be placed as the last node in a workflow branch. It is not a mid-flow control node.

Connect failures to alerts

Debugging after a failure is reactive. The better habit is knowing about failures before someone else does.

n8n's Error Trigger runs a separate workflow when any production workflow fails. That separate workflow sends an alert to Telegram, Slack, Google Chat, email, or wherever your team already pays attention. The execution log gives you the workflow name, failed node, error message, and a link back to the execution.

The full setup, including what the alert should contain and how to point multiple workflows at a single shared error handler, is covered in the n8n error workflow and chat alerts guide.