v1.37.1

n8n-expression-syntax

czlonkowski@czlonkowski⭐ 6.6k stars· last commit 22d ago· 10 open issues

Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, mapping data between nodes, or referencing webhook data in workflows. Use this skill whenever configuring node fields that reference data from previous nodes — expressions are how n8n passes data between nodes, and getting the syntax wrong is the most common source of workflow errors. Also use when asked whether a complex expression hurts performance.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.9/10
Verified
Oct 11, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 6.6k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.9/10
📍

Not yet listed on ClawHub or SkillsMP

// README

n8n Expression Syntax

Expert guide for writing correct n8n expressions in workflows.


Purpose

Teaches correct n8n expression syntax ({{ }} patterns) and fixes common mistakes, especially the critical webhook data structure gotcha.

Activates On

  • expression
  • {{}} syntax
  • $json, $node, $now, $env
  • webhook data
  • troubleshoot expression error
  • undefined in workflow

File Count

4 files

Dependencies

n8n-mcp tools:

  • None directly (syntax knowledge skill)
  • Works with n8n-mcp validation tools

Related skills:

  • n8n Workflow Patterns (uses expressions in examples)
  • n8n MCP Tools Expert (validates expressions)
  • n8n Node Configuration (when expressions are needed)

Coverage

Core Topics

  • Expression format ({{ }})
  • Core variables ($json, $node, $now, $env)
  • Webhook data structure ($json.body.*)
  • When NOT to use expressions (Code nodes)
  • $jmespath(object, query) — querying nested JSON in one expression, with the quoting rules that fail silently
  • Runtime errors inside {{ }} resolve to null (node still succeeds) — how to surface them

Common Patterns

  • Accessing nested fields
  • Referencing other nodes
  • Array and object access
  • Date/time formatting
  • String manipulation

Error Prevention

  • 17 common mistakes with fixes (incl. JMESPath quoting and the silent-null runtime error)
  • Quick reference table
  • Debugging process

Evaluations

6 scenarios (100% coverage expected):

  1. eval-001: Missing curly braces
  2. eval-002: Webhook body data access (critical!)
  3. eval-003: Code node vs expression confusion
  4. eval-004: Node reference syntax
  5. eval-005: $jmespath quoting (double-quoted string, bare number)
  6. eval-006: Filter drops everything on a green run (silent null)

Key Features

✅ Critical Gotcha Highlighted: Webhook data under .body ✅ Real Examples: From MCP testing and real templates ✅ Quick Fixes Table: Fast reference for common errors ✅ Code vs Expression: Clear distinction ✅ Comprehensive: Covers 95% of expression use cases

Files

  • SKILL.md - Main content with all essential knowledge
  • COMMON_MISTAKES.md - Complete error catalog with 15 common mistakes
  • EXAMPLES.md - 10 real working examples
  • README.md (this file) - Skill metadata

Success Metrics

Expected outcomes:

  • Users correctly wrap expressions in {{ }}
  • Zero webhook .body access errors
  • No expressions used in Code nodes
  • Correct $node reference syntax

Last Updated

2025-10-20


Part of: n8n-skills repository Conceived by: Romuald Członkowski - aiadvisors.pl/en

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/n8n-expression-syntax/SKILL.md7.9 KBupstream ↗
    ---
    name: n8n-expression-syntax
    description: Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, mapping data between nodes, or referencing webhook data in workflows. Use this skill whenever configuring node fields that reference data from previous nodes — expressions are how n8n passes data between nodes, and getting the syntax wrong is the most common source of workflow errors. Also use when asked whether a complex expression hurts performance.
    ---
    
    # n8n Expression Syntax
    
    Expert guide for writing correct n8n expressions in workflows.
    
    ---
    
    ## Expression Format
    
    All dynamic content in n8n uses **double curly braces**:
    
    ```
    {{expression}}
    ```
    
    **Examples**:
    ```
    ✅ {{$json.email}}
    ✅ {{$json.body.name}}
    ✅ {{$node["HTTP Request"].json.data}}
    ❌ $json.email  (no braces - treated as literal text)
    ❌ {$json.email}  (single braces - invalid)
    ```
    
    ---
    
    ## Core Variables
    
    ### $json - Current Node Output
    
    Access data from the current node:
    
    ```javascript
    {{$json.fieldName}}
    {{$json['field with spaces']}}
    {{$json.nested.property}}
    {{$json.items[0].name}}
    ```
    
    ### $node - Reference Other Nodes
    
    Access data from any previous node:
    
    ```javascript
    {{$node["Node Name"].json.fieldName}}
    {{$node["HTTP Request"].json.data}}
    {{$node["Webhook"].json.body.email}}
    ```
    
    **Important**:
    - Node names **must** be in quotes
    - Node names are **case-sensitive**
    - Must match exact node name from workflow
    
    ### $now - Current Timestamp
    
    Access current date/time:
    
    ```javascript
    {{$now}}
    {{$now.toFormat('yyyy-MM-dd')}}
    {{$now.toFormat('HH:mm:ss')}}
    {{$now.plus({days: 7})}}
    ```
    
    ### $env - Environment Variables
    
    Access environment variables:
    
    ```javascript
    {{$env.API_KEY}}
    {{$env.DATABASE_URL}}
    ```
    
    **Warning**: Some n8n instances have `N8N_BLOCK_ENV_ACCESS_IN_NODE` enabled, which blocks `$env` access entirely. If `$env` returns errors, use alternative approaches:
    - Store values in credentials instead
    - Use a Set node with manually entered values
    - Pass values through webhook query parameters
    
    ---
    
    ## 🚨 CRITICAL: Webhook Data Structure
    
    **Most Common Mistake**: Webhook data is **NOT** at the root!
    
    ### Webhook Node Output Structure
    
    ```javascript
    {
      "headers": {...},
      "params": {...},
      "query": {...},
      "body": {           // ⚠️ USER DATA IS HERE!
        "name": "John",
        "email": "[email protected]",
        "message": "Hello"
      }
    }
    ```
    
    ### Correct Webhook Data Access
    
    ```javascript
    ❌ WRONG: {{$json.name}}
    ❌ WRONG: {{$json.email}}
    
    ✅ CORRECT: {{$json.body.name}}
    ✅ CORRECT: {{$json.body.email}}
    ✅ CORRECT: {{$json.body.message}}
    ```
    
    **Why**: Webhook node wraps incoming data under `.body` property to preserve headers, params, and query parameters.
    
    ---
    
    ## Common Patterns
    
    ### Access Nested Fields
    
    ```javascript
    // Simple nesting
    {{$json.user.email}}
    
    // Array access
    {{$json.data[0].name}}
    {{$json.items[0].id}}
    
    // Bracket notation for spaces
    {{$json['field name']}}
    {{$json['user data']['first name']}}
    ```
    
    ### Reference Other Nodes
    
    ```javascript
    // Node without spaces
    {{$node["Set"].json.value}}
    
    // Node with spaces (common!)
    {{$node["HTTP Request"].json.data}}
    {{$node["Respond to Webhook"].json.message}}
    
    // Webhook node
    {{$node["Webhook"].json.body.email}}
    ```
    
    ### Combine Variables
    
    ```javascript
    // Concatenation (automatic)
    Hello {{$json.body.name}}!
    
    // In URLs
    https://api.example.com/users/{{$json.body.user_id}}
    
    // In object properties
    {
      "name": "={{$json.body.name}}",
      "email": "={{$json.body.email}}"
    }
    ```
    
    ---
    
    ## When NOT to Use Expressions
    
    ### ❌ Code Nodes
    
    Code nodes use **direct JavaScript access**, NOT expressions!
    
    ```javascript
    // ❌ WRONG in Code node
    const email = '={{$json.email}}';
    const name = '{{$json.body.name}}';
    
    // ✅ CORRECT in Code node
    const email = $json.email;
    const name = $json.body.name;
    
    // Or using Code node API
    const email = $input.item.json.email;
    const allItems = $input.all();
    ```
    
    ### ❌ Webhook Paths
    
    ```javascript
    // ❌ WRONG
    path: "{{$json.user_id}}/webhook"
    
    // ✅ CORRECT
    path: "user-webhook"  // Static paths only
    ```
    
    ### ❌ Credential Fields
    
    ```javascript
    // ❌ WRONG
    apiKey: "={{$env.API_KEY}}"
    
    // ✅ CORRECT
    Use n8n credential system, not expressions
    ```
    
    ---
    
    ## The transform gatekeeper
    
    Before you add any node — or write any code — to transform data, walk this order and stop at the first that fits:
    
    1. **Expression** (`{{ ... }}`) in the consuming field. Property access, method chains (`.map().filter().join()`), ternaries, string building, Luxon date math — if it's "take A, produce B" without intermediate variables, it's an expression. This covers most "just transform this" cases.
       - **Querying nested JSON** (filter an array, pick fields, sum, sort, flatten) → `$jmespath()` inside that same expression, before you split into items or chain `.map().filter()`. One query replaces a Split Out → Filter → Aggregate chain. Rules below.
    2. **Arrow-function IIFE inside an Edit Fields field.** When the logic needs intermediate variables, branching, or comments but still operates on one item, wrap it in an immediately-invoked arrow function right in the field value:
    
       ```
       ={{ (() => {
           const items = $json.line_items;
           const subtotal = items.reduce((sum, it) => sum + it.price * it.qty, 0);
           const tax = subtotal * 0.08;
           return (subtotal + tax).toFixed(2);
       })() }}
       ```
    
       The outer `(...)` brackets the function; the trailing `()` invokes it. Drop either and n8n refuses to run. Inside you get the full expression scope (`$json`, `$('Node')`, `$now`, Luxon) plus `const`/`let`, `if`/`switch`, `try`/`catch`, and regex. No `require`, no `await`.
    3. **Code node — last resort.** Only when you need multi-item aggregation across the whole dataset (`$input.all()`), an allowlisted library, or async work.
    
    **Why the order matters.** It's not style — it's readability and performance. The Code node runs in a sandboxed VM with per-invocation setup and value marshaling — a cold-start cost that can reach 500–1000ms before your logic runs. (It amortizes on warm, high-item-count runs, so treat this as the common-case cost, not a universal constant.) The same logic in an expression or Edit Fields IIFE runs in-process in single-digit milliseconds and skips the sandbox entirely. For pure single-item shaping that's a large gap with no functional difference, and it compounds on hot paths like per-request webhooks. The expression also stays visible in the field that uses it, instead of hiding in an upstream node someone has to open to understand. Reach past a stage only when the input or scope genuinely demands it.
    
    ## `$jmespath()` — query nested JSON in one expression
    
    ```
    {{ $jmespath($json, "customers[?country=='PL' && revenue > `100000`].name") }}    →  ["Acme"]
    ```
    
    Verified on n8n 2.38: this one expression returns exactly what Split Out → Filter → Aggregate
    returns, with no extra nodes. The syntax is unforgiving, and **most mistakes fail silently**:
    
    | Write | Not | What the wrong form does |
    |---|---|---|
    | `$jmespath(object, "query")`, object first | `$jmespath("query", object)` | throws `expected two arguments (Object, string) for this function` (JMESPath's own docs show `search(query, data)`) |
    | strings in single quotes: `country=='PL'` | `country=="PL"` | double quotes mean a **field name** → returns `[]`, no error |
    | numbers/booleans in backticks: `` revenue > `100000` `` | `revenue > 100000` | parse error → whole expression becomes `null` (see Debugging) |
    | `&&` `\|\|` `!` `==` | `and` `or` `=` | parse error → `null` |
    | hyphenated keys quoted: `'customers[*].contact."first-name"'` (single-quote the JS string) | `contact.first-name` | parse error → `null` |
    | over items, keep the wrapper: `$jmespath($('Node').all(), "[?json.country=='PL'].json.name")` or `$jmespath($input.all().map(i => i.json), "[?country=='PL'].name")` | `"[?country=='PL'].name"` on `.all()` | items are `{json: …}` wrappers → `[]` |
    
    - **
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/czlonkowski-n8n-skills-skills-n8n-expression-syntax.md

// REPO STATS

6.6k stars
10 open issues
Last commit: 22d ago