n8n Workflow Builder

Unified expert guidance for building production-ready n8n workflows. Consolidates expression syntax, MCP tool usage, 5 workflow patterns, validation, node configuration, and Code node development.

1. Expression Syntax

Core Syntax

All n8n expressions use double curly braces: {{ expression }}.

Critical Expression Rules

1. •

   Webhook data is ALWAYS nested under $json.body — this is the #1 expression mistake:

   code

   ❌ {{ $json.email }}           → undefined for webhook data
   ✅ {{ $json.body.email }}      → correct webhook access
   

2. •

   Dot notation for simple paths, bracket for special characters:

   code

   ✅ {{ $json.user.name }}
   ✅ {{ $json["first-name"] }}   → hyphens require brackets
   ✅ {{ $json["my field"] }}     → spaces require brackets
   

3. •

   Ternary for conditional values:

   code

   {{ $json.status === "active" ? "Yes" : "No" }}
   

4. •

   Optional chaining to prevent errors:

   code

   {{ $json.user?.address?.city ?? "Unknown" }}
   

5. •

   Date manipulation with Luxon (built-in):

   code

   {{ $now.minus({days: 7}).toISO() }}
   {{ DateTime.fromISO($json.date).toFormat("yyyy-MM-dd") }}
   

Top 5 Expression Mistakes

2. MCP Tool Selection Guide

7 Core MCP Tools — Quick Reference

nodeType Format — CRITICAL

Core nodes:      n8n-nodes-base.slack
                 n8n-nodes-base.httpRequest
                 n8n-nodes-base.webhook

LangChain/AI:    @n8n/n8n-nodes-langchain.agent
                 @n8n/n8n-nodes-langchain.lmChatOpenAi
                 @n8n/n8n-nodes-langchain.memoryBufferWindow

Community:       n8n-nodes-community.customNode

⚠️ Search tools use short format (nodes-base.slack), workflow tools use full format (n8n-nodes-base.slack). The MCP server auto-sanitizes, but always use full format in workflow JSON.

search_nodes Best Practices

search_nodes({query: "slack", includeExamples: true})
search_nodes({query: "AI agent", source: "verified"})
search_nodes({query: "database postgres"})

• •Always set includeExamples: true for configuration examples
• •Use source: "verified" to filter to trusted community nodes
• •Keep queries to 1-3 keywords for best results

get_node Modes and Detail Levels

validate_node Profiles

Validation sequence: minimal first → fix errors → runtime or ai-friendly → fix → validate_workflow.

search_templates searchModes

Filters: complexity, targetAudience, maxSetupMinutes, requiredService.

3. Workflow Patterns

Five proven architectural patterns for n8n workflows. Select based on trigger type and data flow.

Pattern Selection

Pattern 1: Webhook Processing

Webhook → Validate Input → Transform Data → Business Logic → Respond to Webhook
                ↓ (on error)
          Error Response (4xx)

Key rules:

• •Always validate incoming data before processing
• •Always respond with Respond to Webhook node — timeouts cause client errors
• •Access payload via $json.body, headers via $json.headers
• •Add authentication (header check or HMAC) for production webhooks

Pattern 2: HTTP API Integration

Trigger → Set Auth Headers → HTTP Request → IF (status check) → Process Response
                                                    ↓ (on error)
                                              Retry / Error Handler

Key rules:

• •Set continueOnFail: true on HTTP Request to handle errors gracefully
• •Check response status in IF node before processing
• •Implement retry logic for transient failures (429, 503)
• •Store credentials in n8n Credentials, reference via credential ID

Pattern 3: Database Operations

Trigger → Query Source → Transform/Map Fields → Upsert Target → Verify Write

Key rules:

• •Use upsert over insert/update to handle both cases
• •Map fields explicitly in a Set node — never pass raw data
• •Add a verification query after writes for critical operations
• •Use splitInBatches for large datasets (>1000 records)

Pattern 4: AI Agent Workflow

Trigger → Agent → [Tools: HTTP, Code, etc.] → Memory → Output Parser → Response
              ↑        ↓
         LM Chat    ai_tool connections (NOT main)

Key rules:

• •LangChain nodes use @n8n/n8n-nodes-langchain.* nodeType format
• •Agent connections use ai_agent, ai_tool, ai_memory, ai_outputParser — NOT main
• •Use validate_node(profile: 'ai-friendly') for AI nodes
• •Any node can be an AI tool — not just those marked usableAsTool: true
• •Connect LLM to agent via ai_languageModel connection type

Pattern 5: Scheduled Tasks

Schedule Trigger → Fetch Data → Process/Transform → Notify/Store → Log Result

Key rules:

• •Use scheduleTrigger node with cron expressions
• •Add error notification (email/Slack) for failed runs
• •Include execution metadata in logs ($execution.id, $now)
• •Use IF node to skip processing when no new data exists

For full pattern implementations with node configurations, see references/WORKFLOW_PATTERNS.md.

4. Validation & Error Handling

Validation Loop

Expect 2-3 validation iterations per workflow. This is normal.

Build Node Config → validate_node(minimal) → Fix Errors
                                                  ↓
                    validate_node(full, runtime) ← ┘
                              ↓
                    Build Workflow JSON
                              ↓
                    validate_workflow → Fix Errors → Re-validate
                              ↓
                    Deploy (n8n_create_workflow)

Top 9 Error Types — Quick Fix Guide

False Positive Patterns — When to Ignore

These validation warnings can be safely ignored:

1. •Optional property warnings — Properties with defaults don't need explicit values unless overriding
2. •Credential warnings in development — Credentials are environment-specific; validate only on deployment
3. •Expression validation on dynamic values — Expressions referencing runtime data can't be statically validated
4. •Community node warnings — Community nodes may have incomplete validation schemas
5. •Deprecated property warnings — Still functional; update when convenient
6. •AI tool flexibility warnings — Nodes marked as non-tool can still be used as tools

For complete error catalog with fix procedures, see references/ERROR_CATALOG.md.

5. Node Configuration

Operation-Aware Configuration

n8n nodes reveal different required fields based on the selected resource and operation. Always configure in this order:

1. Set resource    → reveals operation options
2. Set operation   → reveals required properties
3. Set required    → reveals optional properties
4. Set optional    → complete configuration

Example — Slack node:

// Step 1-2: Resource + Operation determine required fields
{"resource": "message", "operation": "post"}

// Step 3: Required fields for message.post
{"select": "channel", "channelId": "C123", "text": "Hello"}

// Step 4: Optional enhancements
{"jsonParameters": true, "attachments": [...]}

Property Dependency Chains

Some properties only appear when parent properties have specific values:

resource: "message"
  └→ operation: "post"
       └→ select: "channel"     ← only shown when operation is "post"
            └→ channelId        ← only shown when select is "channel"

Always use get_node(detail: 'standard') to discover the full dependency tree before configuring.

AI Workflow Connection Rules

LangChain nodes use special connection types, NOT the standard main type:

Authentication Patterns

• •OAuth2: Configure via n8n Credentials UI, reference by credential ID in node config
• •API Key: Store in n8n Credentials or $env variables — never hardcode
• •Header Auth: Use Set node before HTTP Request to add Authorization header
• •No Auth: Set authentication: "none" explicitly — don't rely on defaults

6. Code Node Patterns

When to Use Code Nodes

Use standard n8n nodes for 95% of operations. Use Code nodes only when:

• •Complex data transformation that no standard node handles
• •Custom API response parsing
• •Multi-step calculations or conditional logic beyond IF/Switch

JavaScript (Primary — 95% of Code node use)

Mode Selection

Data Access Patterns

// All Items mode (most common — 26% of usage)
const items = $input.all();
return items.map(item => ({
  json: { ...item.json, processed: true }
}));

// First Item mode (25% of usage)
const data = $input.first().json;
return [{ json: { result: data.value * 2 } }];

// Each Item mode (19% of usage)
const item = $input.item;
return [{ json: { ...item.json, transformed: true } }];

// Reference other nodes
const webhookData = $('Webhook').first().json.body;
const httpResult = $('HTTP Request').first().json;

CRITICAL: Return Format

// ✅ MUST return array of objects with "json" key
return [{ json: { name: "Alice", status: "active" } }];

// ✅ Multiple items
return items.map(i => ({ json: { id: i.json.id } }));

// ❌ FAILS — missing json wrapper
return [{ name: "Alice" }];

// ❌ FAILS — not an array
return { json: { name: "Alice" } };

Built-in Helpers

// HTTP requests (no external packages needed)
const response = await $helpers.httpRequest({
  method: 'GET',
  url: 'https://api.example.com/data',
  headers: { 'Authorization': `Bearer ${$env.API_KEY}` }
});
return [{ json: response }];

Top 5 JavaScript Errors

Python (Secondary — 5% of use cases)

Use Python only when specific standard library functions are needed or Python syntax is strongly preferred.

Key Differences from JavaScript

# Data access uses underscore prefix
items = _input.all()          # not $input.all()
first = _input.first()        # not $input.first()
item = _input.item            # not $input.item

# Return format — same structure, Python syntax
return [{"json": {"name": "Alice", "processed": True}}]

# Reference other nodes
webhook = _node["Webhook"].json["body"]

Python Limitations

• •No external libraries — no pandas, numpy, requests, beautifulsoup
• •Standard library only: json, datetime, re, math, collections, itertools, hashlib, base64, urllib
• •No pip install — sandbox environment has no package manager
• •No file system access — cannot read/write files

For production-tested code patterns, see references/CODE_EXAMPLES.md.