n8n is an incredibly powerful tool for building automations, but as workflows grow in complexity, you're bound to encounter errors. A red-bordered node can be frustrating, but with a systematic approach to debugging, you can quickly identify and resolve most issues. The key is understanding where to look and what the common pitfalls are.
This guide covers some of the most common problems you might encounter when building n8n workflows and provides effective strategies for troubleshooting them.
1. "The data you're looking for isn't there" - Expression and Data Path Errors
This is by far the most common issue. You're trying to reference data from a previous node, but your expression is failing.
- Problem: Incorrect Data Path. You're trying to access `{{ $json.id }}` but the data is actually nested inside another object, like `{{ $json.data.id }}`.
- Solution: Use the Variable Selector. Don't try to type expressions from memory. In any expression editor, click on the "Variables" tab on the left. Navigate through the tree of previous nodes and their outputs. Clicking on a data field will automatically insert the correct path into your expression.
- Problem: Node Name Changes. You renamed a node, and now all the expressions that referenced its old name are broken.
- Solution: Pin Data for Stable Reference. Before a node you want to reference, you can pin its data. This makes the data available under a stable name (e.g., `{{ $pinned.data.id }}`) regardless of the node's name. Alternatively, use a "Set" node to give a piece of data a consistent name that you can reference later.
2. "The loop isn't working" - Issues with Item-by-Item Processing
Loops are powerful but can be tricky. A common mistake is trying to process a list of items when a node is only designed to handle one item at a time.
- Problem: Passing a List to a Single-Item Node. You have an array of 10 users from a "Get All Users" node and you pass it directly to a "Send Email" node. The email node only sends one email, using the data from the first user.
- Solution: Use the "Loop Over Items" Node. The "Loop Over Items" node is designed specifically for this. It takes an array as input and runs the subsequent nodes once for each item in that array. Place it after your data-fetching node and before the nodes that need to act on each individual item.
3. "The API request failed" - HTTP Request Node Errors
When an HTTP Request node fails, the error code tells you everything.
- `401 Unauthorized` or `403 Forbidden`: Your authentication is wrong. Double-check your credentials. Is the API key correct? Is it in the right header? Has the OAuth2 token expired? Try re-authenticating your credential in n8n.
- `400 Bad Request`: You're sending the data in the wrong format. The API was expecting JSON, but you sent form-data, or a required field is missing from the body. Carefully read the API documentation for the endpoint you're calling. Use a "Set" or "Code" node before the request to ensure your data is structured exactly as the API expects.
- `404 Not Found`: The URL is wrong. Check for typos in the endpoint path. Are you using a dynamic ID in the URL (e.g., `/users/{{ $json.id }}`) that might be missing or incorrect?
- `429 Too Many Requests`: You've hit the API's rate limit. See our guide on API Integration Patterns for strategies on handling this, such as using the "Retry on Fail" option or building a manual backoff loop with a "Wait" node.
4. "The data format is all wrong" - Merging and Structuring Data
As data flows through multiple branches and merges, its structure can become complex and hard to work with.
- Problem: Confusing Merged Data. A "Merge" node combines data from multiple inputs, which can result in a deeply nested and confusing JSON structure.
- Solution: Use a "Set" Node Immediately After Merging. Add a "Set" node right after the "Merge" node. Use it to "flatten" the data structure. Create a new, clean set of key-value pairs, pulling the specific data you need from the merged inputs using expressions. This gives the rest of your workflow a simple, predictable data structure to work with.
General Debugging Workflow
When you're stuck, follow this simple process:
- Isolate the Problem: Execute nodes one by one to see exactly where the failure occurs.
- Inspect the Input Data: Click on the failing node and look at the "Input" tab on the right. Is the data structured the way you expect? Is anything missing?
- Read the Error Message: Look at the "Output" or "Error" tab. The error message often tells you exactly what's wrong (e.g., "Cannot read property 'id' of undefined").
- Consult the Docs: Check the n8n documentation for the node you're using, and check the API documentation for the service you're calling.
By approaching debugging systematically and understanding these common pitfalls, you can solve problems faster and build more reliable and powerful n8n automations.