N8n

n8n

Expert guidance for building n8n workflows: expressions, Code nodes, node configuration, validation, the n8n-mcp tool surface, and the five production workflow patterns.

Read this file for the rules that apply everywhere, then open the one reference that matches the task.

Which reference to read

Deep dives

Each topic above has companion references, opened from the topic file or directly:

• Expressions: references/expressions-examples.md (real workflow examples), references/expressions-common-mistakes.md (complete error catalogue)
• JavaScript Code node: references/code-javascript-data-access.md, references/code-javascript-common-patterns.md, references/code-javascript-error-patterns.md, references/code-javascript-builtin-functions.md
• Python Code node: references/code-python-data-access.md, references/code-python-common-patterns.md, references/code-python-error-patterns.md, references/code-python-standard-library.md
• Node configuration: references/node-configuration-dependencies.md, references/node-configuration-operation-patterns.md
• Validation: references/validation-error-catalog.md, references/validation-false-positives.md
• n8n-mcp tools: references/mcp-tools-search-guide.md, references/mcp-tools-validation-guide.md, references/mcp-tools-workflow-guide.md
• Workflow patterns: references/workflow-patterns-webhook-processing.md, references/workflow-patterns-http-api-integration.md, references/workflow-patterns-database-operations.md, references/workflow-patterns-ai-agent-workflow.md, references/workflow-patterns-scheduled-tasks.md

Cross-cutting rules

These four rules decide most n8n bugs. They apply across expressions, Code nodes, node parameters and patterns, so they are stated once here; the details stay in the references.

1. Webhook data lives under .body

The Webhook node wraps the incoming request so headers, params and query survive alongside the payload:

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // user data is HERE
    "name": "John",
    "email": "john@example.com"
  }
}

Reaching for the field at the root is the single most common n8n mistake, in every language:

// Expression field
❌ {{$json.name}}          ✅ {{$json.body.name}}

// JavaScript Code node
❌ const name = $json.name;            ✅ const name = $json.body.name;

# Python Code node (per-item mode)
❌ name = _item["json"]["name"]        ✅ name = _item["json"]["body"]["name"]

Details: references/expressions.md, references/workflow-patterns-webhook-processing.md.

2. Expressions and Code nodes are different languages

{{ }} is for node parameter fields. Code nodes run JavaScript or Python directly and never use {{ }}.

Expressions do not evaluate in a webhook path — that route is registered once, so use a route parameter (user/:userId, read back as $json.params.userId) when the path must vary. Credential fields are the opposite case: they do take expressions, and they are the only place $secrets resolves at all. Node names inside $('Node Name') are case-sensitive, must be quoted, and {{ }} never nests.

Reach for a Code node when the logic is a multi-step transformation, a custom calculation, recursion, complex response parsing or cross-item aggregation. Reach for Set, Filter, IF/Switch or HTTP Request when it is field mapping, basic filtering, a simple conditional or a plain request.

Details: references/expressions.md, references/code-javascript.md, references/code-python.md.

3. Choose the Code node mode, then return the right shape

Code nodes offer two execution modes. Run Once for All Items is the default and the right answer for most work — the code runs once with the whole batch, so aggregation, sorting, deduplication and top-N are possible. Run Once for Each Item runs the code per item and only exposes $input.item (JavaScript) or _item (Python); use it when each item is genuinely independent and the per-item code is simple. Python's whole surface is _items in all-items mode and _item per item, with bracket access only.

Whichever mode, the return value must be an array (JavaScript) or list (Python) of objects each carrying a json key:

// JavaScript
return [{json: {result: "value"}}];              // ✅
return {result: "value"};                        // ❌ not wrapped
return [{result: "value"}];                      // ❌ missing json key

// Python
return [{"json": {"result": "value"}}]           # ✅
return {"result": "value"}                       # ❌ dict without list wrapper

Python imports are allowlisted on the task runner, not free: the standard library needs N8N_RUNNERS_STDLIB_ALLOW and third-party packages need N8N_RUNNERS_EXTERNAL_ALLOW plus an extended n8nio/runners image — and n8n Cloud permits no imports at all. Native Python also requires task runners in external mode. When an import is blocked, use an HTTP Request node, or switch to JavaScript and this.helpers.httpRequest(), which is the default language for a reason.

Details: references/code-javascript.md, references/code-python.md, references/code-python-standard-library.md.

4. Validate before you deploy, and iterate

Configuration is not finished when it looks right; it is finished when validation passes. The loop that works:

1. Configure node
   ↓
2. validate_node({nodeType, config, mode: "full", profile: "runtime"})
   ↓
3. Read the error messages carefully
   ↓
4. Fix errors
   ↓
5. validate_node again
   ↓
6. Repeat until valid (usually 2-3 iterations)

Then validate the assembled workflow with validate_workflow before you create it.

A validated workflow is still a draft. n8n 2.0 replaced activate/deactivate with a draft/publish model: saving changes nothing about what runs until you publish, so finish with the activateWorkflow operation on n8n_update_partial_workflow (or publish:workflow --id=<ID> on the CLI). "I saved it and nothing happened" is almost always an unpublished draft.

Pick the profile that matches the stage:

Name the profile explicitly: validate_node defaults to ai-friendly, validate_workflow defaults to runtime. Errors must be fixed. Warnings should be fixed. Suggestions are optional. Some warnings are known false positives — check before chasing them.

Details: references/validation.md, references/validation-false-positives.md, references/mcp-tools-validation-guide.md.

Working with n8n-mcp

When the n8n-mcp server is available, the usual sequence is discover → configure → validate → build:

1. search_nodes({query: "..."}) to find the node
2. get_node({nodeType: "nodes-base.<node>"}) for the fields that matter — detail defaults to standard, and detail: "full" returns the entire schema, which is rarely what you want
3. validate_node({nodeType, config, mode: "full", profile: "runtime"}) on the configuration, iterating as above
4. n8n_create_workflow / n8n_update_partial_workflow to build and edit
5. validate_workflow on the finished structure
6. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]}) to publish it

There are 28 tools: 7 core ones that need no n8n instance (tools_documentation, search_nodes, get_node, validate_node, validate_workflow, search_templates, get_template) and 21 management tools behind N8N_API_URL + N8N_API_KEY. Each core tool absorbed several older single-purpose tools behind a detail, mode or searchMode argument, so a call written against an earlier generation fails with "unknown tool".

Node type strings come in two formats and mixing them is a frequent failure: search and validation tools take the short form (nodes-base.slack), workflow tools take the full form (n8n-nodes-base.slack).

Details: references/mcp-tools.md, references/mcp-tools-search-guide.md, references/mcp-tools-workflow-guide.md.

The five workflow patterns

Start from the pattern that matches the trigger and the destination, then fill in the nodes:

Selection guidance, the shared components of every pattern, and the full worked examples live in references/workflow-patterns.md.

Attribution

Conceived as the n8n-mcp project by Romuald Czlonkowski (aiadvisors.pl), adapted and maintained by AeyeOps — see NOTICE.md at the plugin root.