n8n Code Node

Complete reference for the n8n v1.x Code node — JavaScript and Python modes, execution models, available variables, binary data, restrictions, and return format.

Quick Reference

CRITICAL: 5 Restrictions

These restrictions apply to ALL Code node executions. Violating them causes runtime errors.

1. NO filesystem access — NEVER use fs, path, or any file I/O. Use Read/Write Files From Disk nodes instead.
2. NO HTTP requests — NEVER use fetch, axios, or http. Use the HTTP Request node instead.
3. NO `$itemIndex` — This variable is NOT available in the Code node. Track index manually with a loop counter.
4. NO `$secrets` — External secrets are NOT accessible in Code node. Pass secret values through preceding node output.
5. NO `$parameter` — Node configuration parameters are NOT available. Hardcode values or pass them as input data.

Execution Mode Decision Tree

Need to write Code node logic?
├── Processing items independently (filter, transform, enrich)?
│   └── Use "Run Once for Each Item"
│       ├── JS: access current item via $input.item.json
│       └── Python: access current item via _item["json"]
├── Need to compare/aggregate across ALL items (sort, deduplicate, summarize)?
│   └── Use "Run Once for All Items" (default)
│       ├── JS: access all items via items array
│       └── Python: access all items via _items list
└── Can a native node do this instead (Set, Filter, Sort, Merge)?
    └── ALWAYS prefer native nodes — they are faster and maintain item linking

Return Format

Run Once for All Items — MUST Return Array

// JavaScript — ALWAYS return an array of {json: {...}} objects
return items.map(item => ({
  json: { name: item.json.name, processed: true }
}));

# Python — ALWAYS return a list of {"json": {...}} dicts
return [{"json": {"name": item["json"]["name"], "processed": True}} for item in _items]

Run Once for Each Item — Return Single Object

// JavaScript — return ONE {json: {...}} object
return { json: { name: $input.item.json.name, processed: true } };

# Python — return ONE {"json": {...}} dict
return {"json": {"name": _item["json"]["name"], "processed": True}}

NEVER return raw data without the json wrapper. The format {json: {...}} is mandatory.

Available Variables

JavaScript Variables

Python Variables

Python uses _ prefix instead of $:

Python-specific rules:

• ALWAYS use bracket notation: item["json"]["field"] — dot notation fails
• On n8n Cloud: NEVER import external libraries
• Self-hosted: standard library + allowlisted third-party modules only
• getBinaryDataBuffer() is NOT supported in Python

Binary Data Handling

// Get binary buffer (JavaScript only, NOT available in Python)
const buffer = await this.helpers.getBinaryDataBuffer(itemIndex, 'data');

// Create new item with binary data from base64
return [{
  json: { fileName: 'output.txt' },
  binary: {
    data: await this.helpers.prepareBinaryData(
      Buffer.from('file content', 'utf-8'),
      'output.txt',
      'text/plain'
    )
  }
}];

NEVER access binary data directly via items[0].binary.data.data. ALWAYS use getBinaryDataBuffer().

Built-in Modules

Item Linking in Code Node

ALWAYS use $("<node>").itemMatching(index) in Code node — NOT $("<node>").item:

// Correct — Code node item tracing
const originalData = $("HTTP Request").itemMatching(0).json;

// Wrong — .item does not work reliably in Code node
// const originalData = $("HTTP Request").item.json;

Error Handling

// Try-catch pattern for Code node
try {
  const value = items[0].json.requiredField;
  if (!value) throw new Error('requiredField is missing');
  return [{ json: { result: value } }];
} catch (error) {
  // Return error as data (workflow continues)
  return [{ json: { error: error.message } }];
}

When NOT to Use Code Node

ALWAYS prefer native nodes for these operations:

Native nodes are faster (no sandbox overhead) and maintain automatic item linking.

Reference Files

• references/methods.md — Complete variable reference per mode, built-in modules, return format details
• references/examples.md — JavaScript and Python patterns: item manipulation, binary data, aggregation
• references/anti-patterns.md — Common Code node mistakes with corrections

Sources

• n8n Code node documentation: n8n-io/n8n-docs (main branch)
• n8n Code node source: packages/nodes-base/nodes/Code/Code.node.ts
• n8n Expression reference: docs/data/expression-reference/
• n8n Binary data reference: docs/data/specific-data-types/binary-data.md