chore: import upstream snapshot with attribution
Build and Push Docker Images / Build Docker Image (push) Has been cancelled
Build and Push Docker Images / Build Railway Docker Image (push) Has been cancelled
Build and Publish n8n Docker Image / test-image (push) Has been cancelled
Dependency Compatibility Check / Fresh Install Dependency Check (push) Has been cancelled
Build and Publish n8n Docker Image / build-and-push (push) Has been cancelled
Build and Publish n8n Docker Image / create-release (push) Has been cancelled
Automated Release / Detect Version Change (push) Has been cancelled
Automated Release / Generate Release Notes (push) Has been cancelled
Automated Release / Create GitHub Release (push) Has been cancelled
Automated Release / Package MCPB Bundle (push) Has been cancelled
Automated Release / Build and Verify (push) Has been cancelled
Automated Release / Publish to NPM (push) Has been cancelled
Automated Release / Build and Push Docker Images (push) Has been cancelled
Automated Release / Update Documentation (push) Has been cancelled
Automated Release / Notify Release Completion (push) Has been cancelled
Secret Scan / secretlint (push) Has been cancelled
Test Suite / test (push) Has been cancelled
Test Suite / cjs-runtime (push) Has been cancelled
Test Suite / publish-results (push) Has been cancelled
Build and Push Docker Images / Build Docker Image (push) Has been cancelled
Build and Push Docker Images / Build Railway Docker Image (push) Has been cancelled
Build and Publish n8n Docker Image / test-image (push) Has been cancelled
Dependency Compatibility Check / Fresh Install Dependency Check (push) Has been cancelled
Build and Publish n8n Docker Image / build-and-push (push) Has been cancelled
Build and Publish n8n Docker Image / create-release (push) Has been cancelled
Automated Release / Detect Version Change (push) Has been cancelled
Automated Release / Generate Release Notes (push) Has been cancelled
Automated Release / Create GitHub Release (push) Has been cancelled
Automated Release / Package MCPB Bundle (push) Has been cancelled
Automated Release / Build and Verify (push) Has been cancelled
Automated Release / Publish to NPM (push) Has been cancelled
Automated Release / Build and Push Docker Images (push) Has been cancelled
Automated Release / Update Documentation (push) Has been cancelled
Automated Release / Notify Release Completion (push) Has been cancelled
Secret Scan / secretlint (push) Has been cancelled
Test Suite / test (push) Has been cancelled
Test Suite / cjs-runtime (push) Has been cancelled
Test Suite / publish-results (push) Has been cancelled
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,827 @@
|
||||
# Built-in Functions - JavaScript Code Node
|
||||
|
||||
Complete reference for n8n's built-in JavaScript functions and helpers.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
n8n Code nodes provide powerful built-in functions beyond standard JavaScript. This guide covers:
|
||||
|
||||
1. **Sandbox restrictions** - What's blocked and why (READ FIRST)
|
||||
2. **this.helpers.httpRequest()** - Make HTTP requests (the bare `$helpers` global is undefined in the task runner)
|
||||
3. **DateTime (Luxon)** - Advanced date/time operations
|
||||
4. **$jmespath()** - Query JSON structures
|
||||
5. **$getWorkflowStaticData()** - Persistent storage
|
||||
6. **Standard JavaScript Globals** - Math, JSON, console, etc.
|
||||
7. **Available Node.js Modules** - crypto, Buffer, URL
|
||||
|
||||
---
|
||||
|
||||
## 0. Sandbox Restrictions (Critical)
|
||||
|
||||
Since n8n v2.0, Code nodes execute inside a **task runner sandbox** (`JsTaskRunnerSandbox`) which deliberately blocks several APIs. The legacy vm2 sandbox is being removed. Knowing what's blocked saves hours of "why does this throw on activation but not in the editor preview."
|
||||
|
||||
### Blocked helpers
|
||||
|
||||
```javascript
|
||||
// ❌ BLOCKED — throws UnsupportedFunctionError
|
||||
await this.helpers.httpRequestWithAuthentication.call(this, 'credType', { ... });
|
||||
await this.helpers.requestWithAuthenticationPaginated.call(this, { ... }, 'credType');
|
||||
```
|
||||
|
||||
n8n's source comment explains why: *"these rely on checking the credentials from the current node type (Code Node), and Code Node doesn't have credentials."* There is **no env var to re-enable them** in the task runner — the deny-list is compiled-in (`packages/@n8n/task-runner/src/runner-types.ts`).
|
||||
|
||||
**Workaround**: don't try to authenticate from inside a Code node. Instead, either:
|
||||
- Replace the Code node with an HTTP Request node that has the credential attached (the canonical pattern), or
|
||||
- Have the Code node prepare a payload and delegate to a sub-workflow whose HTTP Request node holds the credential.
|
||||
|
||||
### `$env` may be blocked
|
||||
|
||||
`$env` is gated by **`N8N_BLOCK_ENV_ACCESS_IN_NODE`**. When set to `true` (a common production hardening), any reference to `$env.SOMETHING` throws. Since you can't tell from inside the Code node whether it's enabled, **don't rely on `$env` for portable skills** — treat secrets as a credential concern (HTTP Request node) rather than a Code-node concern.
|
||||
|
||||
### `require()` is gated by allowlists
|
||||
|
||||
```javascript
|
||||
// May throw "Cannot find module 'crypto'" — depends on env vars
|
||||
const crypto = require('crypto');
|
||||
```
|
||||
|
||||
Built-in modules need `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` (or legacy `NODE_FUNCTION_ALLOW_BUILTIN`) set to `*` or a comma-list including `crypto`. External npm packages need `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` plus the package being installed in the runner image. On default installs neither is set — `require()` throws.
|
||||
|
||||
`Buffer` and `URL` are globals (not `require`'d), so they always work.
|
||||
|
||||
### What's always safe
|
||||
|
||||
`$input.*`, `$json`, `$node[…]`, `this.helpers.httpRequest()` (without auth), `$jmespath()`, `$getWorkflowStaticData()`, `DateTime` (Luxon), and all standard JavaScript globals (`Math`, `JSON`, `Object`, `Array`, `console`, `Buffer`, `URL`, `URLSearchParams`).
|
||||
|
||||
> **Accessor gotcha**: the bare `$helpers` global is **undefined** in the task-runner sandbox — `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`. The working accessor is **`this.helpers.httpRequest()`** (inside a nested async function where `this` is lost, call it as `await fn.call(this, ...)`). The n8n-mcp validator may wrongly suggest `$helpers` — ignore it. And for anything beyond a trivial unauthenticated GET (pagination, retries, credentials), prefer the **HTTP Request node** and keep Code nodes for pure logic.
|
||||
|
||||
---
|
||||
|
||||
## 1. this.helpers.httpRequest() - HTTP Requests
|
||||
|
||||
Make HTTP requests directly from Code nodes without using HTTP Request node. The accessor is `this.helpers.httpRequest()` — the bare `$helpers` global is undefined in the task-runner sandbox and throws `ReferenceError: $helpers is not defined`. For non-trivial calls (pagination, retries, credentials) prefer the HTTP Request node.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
const response = await this.helpers.httpRequest({
|
||||
method: 'GET',
|
||||
url: 'https://api.example.com/users'
|
||||
});
|
||||
|
||||
return [{json: {data: response}}];
|
||||
```
|
||||
|
||||
### Complete Options
|
||||
|
||||
```javascript
|
||||
const response = await this.helpers.httpRequest({
|
||||
method: 'POST', // GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
|
||||
url: 'https://api.example.com/users',
|
||||
headers: {
|
||||
'Authorization': 'Bearer token123',
|
||||
'Content-Type': 'application/json',
|
||||
'User-Agent': 'n8n-workflow'
|
||||
},
|
||||
body: {
|
||||
name: 'John Doe',
|
||||
email: 'john@example.com'
|
||||
},
|
||||
qs: { // Query string parameters
|
||||
page: 1,
|
||||
limit: 10
|
||||
},
|
||||
timeout: 10000, // Milliseconds (default: no timeout)
|
||||
json: true, // Auto-parse JSON response (default: true)
|
||||
simple: false, // Don't throw on HTTP errors (default: true)
|
||||
resolveWithFullResponse: false // Return only body (default: false)
|
||||
});
|
||||
```
|
||||
|
||||
### GET Request
|
||||
|
||||
```javascript
|
||||
// Simple GET
|
||||
const users = await this.helpers.httpRequest({
|
||||
method: 'GET',
|
||||
url: 'https://api.example.com/users'
|
||||
});
|
||||
|
||||
return [{json: {users}}];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// GET with query parameters
|
||||
const results = await this.helpers.httpRequest({
|
||||
method: 'GET',
|
||||
url: 'https://api.example.com/search',
|
||||
qs: {
|
||||
q: 'javascript',
|
||||
page: 1,
|
||||
per_page: 50
|
||||
}
|
||||
});
|
||||
|
||||
return [{json: results}];
|
||||
```
|
||||
|
||||
### POST Request
|
||||
|
||||
```javascript
|
||||
// POST with JSON body
|
||||
// NOTE: For authenticated APIs, prefer an HTTP Request node with a credential
|
||||
// attached. Embedding the token in a Code node only works when (a) the token
|
||||
// arrives as runtime data (e.g. from a previous node), or (b) you're sure
|
||||
// $env access is enabled on this instance. See section 0.
|
||||
const apiToken = $input.first().json.apiToken; // passed in from a credential-aware upstream node
|
||||
|
||||
const newUser = await this.helpers.httpRequest({
|
||||
method: 'POST',
|
||||
url: 'https://api.example.com/users',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${apiToken}`
|
||||
},
|
||||
body: {
|
||||
name: $json.body.name,
|
||||
email: $json.body.email,
|
||||
role: 'user'
|
||||
}
|
||||
});
|
||||
|
||||
return [{json: newUser}];
|
||||
```
|
||||
|
||||
### PUT/PATCH Request
|
||||
|
||||
```javascript
|
||||
// Update resource
|
||||
const updated = await this.helpers.httpRequest({
|
||||
method: 'PATCH',
|
||||
url: `https://api.example.com/users/${userId}`,
|
||||
body: {
|
||||
name: 'Updated Name',
|
||||
status: 'active'
|
||||
}
|
||||
});
|
||||
|
||||
return [{json: updated}];
|
||||
```
|
||||
|
||||
### DELETE Request
|
||||
|
||||
```javascript
|
||||
// Delete resource
|
||||
await this.helpers.httpRequest({
|
||||
method: 'DELETE',
|
||||
url: `https://api.example.com/users/${userId}`,
|
||||
headers: {
|
||||
'Authorization': `Bearer ${apiToken}` // token passed in from upstream node, not $env
|
||||
}
|
||||
});
|
||||
|
||||
return [{json: {deleted: true, userId}}];
|
||||
```
|
||||
|
||||
### Authentication Patterns
|
||||
|
||||
> **Strong preference**: don't authenticate from inside a Code node. Use an HTTP Request node with a credential attached, or delegate to a sub-workflow whose HTTP Request node holds the credential. The patterns below only apply when the token genuinely flows through the workflow as data.
|
||||
|
||||
```javascript
|
||||
// Bearer Token (token came from a previous node, not $env)
|
||||
const response = await this.helpers.httpRequest({
|
||||
url: 'https://api.example.com/data',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${$input.first().json.token}`
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// API Key in Header (key came from a previous node, not $env)
|
||||
const response = await this.helpers.httpRequest({
|
||||
url: 'https://api.example.com/data',
|
||||
headers: {
|
||||
'X-API-Key': $input.first().json.apiKey
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Basic Auth (manual)
|
||||
const credentials = Buffer.from(`${username}:${password}`).toString('base64');
|
||||
|
||||
const response = await this.helpers.httpRequest({
|
||||
url: 'https://api.example.com/data',
|
||||
headers: {
|
||||
'Authorization': `Basic ${credentials}`
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```javascript
|
||||
// Handle HTTP errors gracefully
|
||||
try {
|
||||
const response = await this.helpers.httpRequest({
|
||||
method: 'GET',
|
||||
url: 'https://api.example.com/users',
|
||||
simple: false // Don't throw on 4xx/5xx
|
||||
});
|
||||
|
||||
if (response.statusCode >= 200 && response.statusCode < 300) {
|
||||
return [{json: {success: true, data: response.body}}];
|
||||
} else {
|
||||
return [{
|
||||
json: {
|
||||
success: false,
|
||||
status: response.statusCode,
|
||||
error: response.body
|
||||
}
|
||||
}];
|
||||
}
|
||||
} catch (error) {
|
||||
return [{
|
||||
json: {
|
||||
success: false,
|
||||
error: error.message
|
||||
}
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
### Full Response Access
|
||||
|
||||
```javascript
|
||||
// Get full response including headers and status
|
||||
const response = await this.helpers.httpRequest({
|
||||
url: 'https://api.example.com/data',
|
||||
resolveWithFullResponse: true
|
||||
});
|
||||
|
||||
return [{
|
||||
json: {
|
||||
statusCode: response.statusCode,
|
||||
headers: response.headers,
|
||||
body: response.body,
|
||||
rateLimit: response.headers['x-ratelimit-remaining']
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. DateTime (Luxon) - Date & Time Operations
|
||||
|
||||
n8n includes Luxon for powerful date/time handling. Access via `DateTime` global.
|
||||
|
||||
### Current Date/Time
|
||||
|
||||
```javascript
|
||||
// Current time
|
||||
const now = DateTime.now();
|
||||
|
||||
// Current time in specific timezone
|
||||
const nowTokyo = DateTime.now().setZone('Asia/Tokyo');
|
||||
|
||||
// Today at midnight
|
||||
const today = DateTime.now().startOf('day');
|
||||
|
||||
return [{
|
||||
json: {
|
||||
iso: now.toISO(), // "2025-01-20T15:30:00.000Z"
|
||||
formatted: now.toFormat('yyyy-MM-dd HH:mm:ss'), // "2025-01-20 15:30:00"
|
||||
unix: now.toSeconds(), // Unix timestamp
|
||||
millis: now.toMillis() // Milliseconds since epoch
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Formatting Dates
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
|
||||
return [{
|
||||
json: {
|
||||
isoFormat: now.toISO(), // ISO 8601: "2025-01-20T15:30:00.000Z"
|
||||
sqlFormat: now.toSQL(), // SQL: "2025-01-20 15:30:00.000"
|
||||
httpFormat: now.toHTTP(), // HTTP: "Mon, 20 Jan 2025 15:30:00 GMT"
|
||||
|
||||
// Custom formats
|
||||
dateOnly: now.toFormat('yyyy-MM-dd'), // "2025-01-20"
|
||||
timeOnly: now.toFormat('HH:mm:ss'), // "15:30:00"
|
||||
readable: now.toFormat('MMMM dd, yyyy'), // "January 20, 2025"
|
||||
compact: now.toFormat('yyyyMMdd'), // "20250120"
|
||||
withDay: now.toFormat('EEEE, MMMM dd, yyyy'), // "Monday, January 20, 2025"
|
||||
custom: now.toFormat('dd/MM/yy HH:mm') // "20/01/25 15:30"
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Parsing Dates
|
||||
|
||||
```javascript
|
||||
// From ISO string
|
||||
const dt1 = DateTime.fromISO('2025-01-20T15:30:00');
|
||||
|
||||
// From specific format
|
||||
const dt2 = DateTime.fromFormat('01/20/2025', 'MM/dd/yyyy');
|
||||
|
||||
// From SQL
|
||||
const dt3 = DateTime.fromSQL('2025-01-20 15:30:00');
|
||||
|
||||
// From Unix timestamp
|
||||
const dt4 = DateTime.fromSeconds(1737384600);
|
||||
|
||||
// From milliseconds
|
||||
const dt5 = DateTime.fromMillis(1737384600000);
|
||||
|
||||
return [{json: {parsed: dt1.toISO()}}];
|
||||
```
|
||||
|
||||
### Date Arithmetic
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
|
||||
return [{
|
||||
json: {
|
||||
// Adding time
|
||||
tomorrow: now.plus({days: 1}).toISO(),
|
||||
nextWeek: now.plus({weeks: 1}).toISO(),
|
||||
nextMonth: now.plus({months: 1}).toISO(),
|
||||
inTwoHours: now.plus({hours: 2}).toISO(),
|
||||
|
||||
// Subtracting time
|
||||
yesterday: now.minus({days: 1}).toISO(),
|
||||
lastWeek: now.minus({weeks: 1}).toISO(),
|
||||
lastMonth: now.minus({months: 1}).toISO(),
|
||||
twoHoursAgo: now.minus({hours: 2}).toISO(),
|
||||
|
||||
// Complex operations
|
||||
in90Days: now.plus({days: 90}).toFormat('yyyy-MM-dd'),
|
||||
in6Months: now.plus({months: 6}).toFormat('yyyy-MM-dd')
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Time Comparisons
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
const targetDate = DateTime.fromISO('2025-12-31');
|
||||
|
||||
return [{
|
||||
json: {
|
||||
// Comparisons
|
||||
isFuture: targetDate > now,
|
||||
isPast: targetDate < now,
|
||||
isEqual: targetDate.equals(now),
|
||||
|
||||
// Differences
|
||||
daysUntil: targetDate.diff(now, 'days').days,
|
||||
hoursUntil: targetDate.diff(now, 'hours').hours,
|
||||
monthsUntil: targetDate.diff(now, 'months').months,
|
||||
|
||||
// Detailed difference
|
||||
detailedDiff: targetDate.diff(now, ['months', 'days', 'hours']).toObject()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Timezone Operations
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
|
||||
return [{
|
||||
json: {
|
||||
// Current timezone
|
||||
local: now.toISO(),
|
||||
|
||||
// Convert to different timezone
|
||||
tokyo: now.setZone('Asia/Tokyo').toISO(),
|
||||
newYork: now.setZone('America/New_York').toISO(),
|
||||
london: now.setZone('Europe/London').toISO(),
|
||||
utc: now.toUTC().toISO(),
|
||||
|
||||
// Get timezone info
|
||||
timezone: now.zoneName, // "America/Los_Angeles"
|
||||
offset: now.offset, // Offset in minutes
|
||||
offsetFormatted: now.toFormat('ZZ') // "+08:00"
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Start/End of Period
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
|
||||
return [{
|
||||
json: {
|
||||
startOfDay: now.startOf('day').toISO(),
|
||||
endOfDay: now.endOf('day').toISO(),
|
||||
startOfWeek: now.startOf('week').toISO(),
|
||||
endOfWeek: now.endOf('week').toISO(),
|
||||
startOfMonth: now.startOf('month').toISO(),
|
||||
endOfMonth: now.endOf('month').toISO(),
|
||||
startOfYear: now.startOf('year').toISO(),
|
||||
endOfYear: now.endOf('year').toISO()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Weekday & Month Info
|
||||
|
||||
```javascript
|
||||
const now = DateTime.now();
|
||||
|
||||
return [{
|
||||
json: {
|
||||
// Day info
|
||||
weekday: now.weekday, // 1 = Monday, 7 = Sunday
|
||||
weekdayShort: now.weekdayShort, // "Mon"
|
||||
weekdayLong: now.weekdayLong, // "Monday"
|
||||
isWeekend: now.weekday > 5, // Saturday or Sunday
|
||||
|
||||
// Month info
|
||||
month: now.month, // 1-12
|
||||
monthShort: now.monthShort, // "Jan"
|
||||
monthLong: now.monthLong, // "January"
|
||||
|
||||
// Year info
|
||||
year: now.year, // 2025
|
||||
quarter: now.quarter, // 1-4
|
||||
daysInMonth: now.daysInMonth // 28-31
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. $jmespath() - JSON Querying
|
||||
|
||||
Query and transform JSON structures using JMESPath syntax.
|
||||
|
||||
### Basic Queries
|
||||
|
||||
```javascript
|
||||
const data = $input.first().json;
|
||||
|
||||
// Extract specific field
|
||||
const names = $jmespath(data, 'users[*].name');
|
||||
|
||||
// Filter array
|
||||
const adults = $jmespath(data, 'users[?age >= `18`]');
|
||||
|
||||
// Get specific index
|
||||
const firstUser = $jmespath(data, 'users[0]');
|
||||
|
||||
return [{json: {names, adults, firstUser}}];
|
||||
```
|
||||
|
||||
### Advanced Queries
|
||||
|
||||
```javascript
|
||||
const data = $input.first().json;
|
||||
|
||||
// Sort and slice
|
||||
const top5 = $jmespath(data, 'users | sort_by(@, &score) | reverse(@) | [0:5]');
|
||||
|
||||
// Extract nested fields
|
||||
const emails = $jmespath(data, 'users[*].contact.email');
|
||||
|
||||
// Multi-field extraction
|
||||
const simplified = $jmespath(data, 'users[*].{name: name, email: contact.email}');
|
||||
|
||||
// Conditional filtering
|
||||
const premium = $jmespath(data, 'users[?subscription.tier == `premium`]');
|
||||
|
||||
return [{json: {top5, emails, simplified, premium}}];
|
||||
```
|
||||
|
||||
### Common Patterns
|
||||
|
||||
```javascript
|
||||
// Pattern 1: Filter and project
|
||||
const query1 = $jmespath(data, 'products[?price > `100`].{name: name, price: price}');
|
||||
|
||||
// Pattern 2: Aggregate functions
|
||||
const query2 = $jmespath(data, 'sum(products[*].price)');
|
||||
const query3 = $jmespath(data, 'max(products[*].price)');
|
||||
const query4 = $jmespath(data, 'length(products)');
|
||||
|
||||
// Pattern 3: Nested filtering
|
||||
const query5 = $jmespath(data, 'categories[*].products[?inStock == `true`]');
|
||||
|
||||
return [{json: {query1, query2, query3, query4, query5}}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. $getWorkflowStaticData() - Persistent Storage
|
||||
|
||||
Store data that persists across workflow executions.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// Get static data storage
|
||||
const staticData = $getWorkflowStaticData();
|
||||
|
||||
// Initialize counter if doesn't exist
|
||||
if (!staticData.counter) {
|
||||
staticData.counter = 0;
|
||||
}
|
||||
|
||||
// Increment counter
|
||||
staticData.counter++;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
executionCount: staticData.counter
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Use Cases
|
||||
|
||||
```javascript
|
||||
// Use Case 1: Rate limiting
|
||||
const staticData = $getWorkflowStaticData();
|
||||
const now = Date.now();
|
||||
|
||||
if (!staticData.lastRun) {
|
||||
staticData.lastRun = now;
|
||||
staticData.runCount = 1;
|
||||
} else {
|
||||
const timeSinceLastRun = now - staticData.lastRun;
|
||||
|
||||
if (timeSinceLastRun < 60000) { // Less than 1 minute
|
||||
return [{json: {error: 'Rate limit: wait 1 minute between runs'}}];
|
||||
}
|
||||
|
||||
staticData.lastRun = now;
|
||||
staticData.runCount++;
|
||||
}
|
||||
|
||||
return [{json: {allowed: true, totalRuns: staticData.runCount}}];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Use Case 2: Tracking last processed ID
|
||||
const staticData = $getWorkflowStaticData();
|
||||
const currentItems = $input.all();
|
||||
|
||||
// Get last processed ID
|
||||
const lastId = staticData.lastProcessedId || 0;
|
||||
|
||||
// Filter only new items
|
||||
const newItems = currentItems.filter(item => item.json.id > lastId);
|
||||
|
||||
// Update last processed ID
|
||||
if (newItems.length > 0) {
|
||||
staticData.lastProcessedId = Math.max(...newItems.map(item => item.json.id));
|
||||
}
|
||||
|
||||
return newItems;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Use Case 3: Accumulating results
|
||||
const staticData = $getWorkflowStaticData();
|
||||
|
||||
if (!staticData.accumulated) {
|
||||
staticData.accumulated = [];
|
||||
}
|
||||
|
||||
// Add current items to accumulated list
|
||||
const currentData = $input.all().map(item => item.json);
|
||||
staticData.accumulated.push(...currentData);
|
||||
|
||||
return [{
|
||||
json: {
|
||||
currentBatch: currentData.length,
|
||||
totalAccumulated: staticData.accumulated.length,
|
||||
allData: staticData.accumulated
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Standard JavaScript Globals
|
||||
|
||||
### Math Object
|
||||
|
||||
```javascript
|
||||
return [{
|
||||
json: {
|
||||
// Rounding
|
||||
rounded: Math.round(3.7), // 4
|
||||
floor: Math.floor(3.7), // 3
|
||||
ceil: Math.ceil(3.2), // 4
|
||||
|
||||
// Min/Max
|
||||
max: Math.max(1, 5, 3, 9, 2), // 9
|
||||
min: Math.min(1, 5, 3, 9, 2), // 1
|
||||
|
||||
// Random
|
||||
random: Math.random(), // 0-1
|
||||
randomInt: Math.floor(Math.random() * 100), // 0-99
|
||||
|
||||
// Other
|
||||
abs: Math.abs(-5), // 5
|
||||
sqrt: Math.sqrt(16), // 4
|
||||
pow: Math.pow(2, 3) // 8
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### JSON Object
|
||||
|
||||
```javascript
|
||||
// Parse JSON string
|
||||
const jsonString = '{"name": "John", "age": 30}';
|
||||
const parsed = JSON.parse(jsonString);
|
||||
|
||||
// Stringify object
|
||||
const obj = {name: "John", age: 30};
|
||||
const stringified = JSON.stringify(obj);
|
||||
|
||||
// Pretty print
|
||||
const pretty = JSON.stringify(obj, null, 2);
|
||||
|
||||
return [{json: {parsed, stringified, pretty}}];
|
||||
```
|
||||
|
||||
### console Object
|
||||
|
||||
```javascript
|
||||
// Debug logging (appears in browser console, press F12)
|
||||
console.log('Processing items:', $input.all().length);
|
||||
console.log('First item:', $input.first().json);
|
||||
|
||||
// Other console methods
|
||||
console.error('Error message');
|
||||
console.warn('Warning message');
|
||||
console.info('Info message');
|
||||
|
||||
// Continues to return data
|
||||
return [{json: {processed: true}}];
|
||||
```
|
||||
|
||||
### Object Methods
|
||||
|
||||
```javascript
|
||||
const obj = {name: "John", age: 30, city: "NYC"};
|
||||
|
||||
return [{
|
||||
json: {
|
||||
keys: Object.keys(obj), // ["name", "age", "city"]
|
||||
values: Object.values(obj), // ["John", 30, "NYC"]
|
||||
entries: Object.entries(obj), // [["name", "John"], ...]
|
||||
|
||||
// Check property
|
||||
hasName: 'name' in obj, // true
|
||||
|
||||
// Merge objects
|
||||
merged: Object.assign({}, obj, {country: "USA"})
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Array Methods
|
||||
|
||||
```javascript
|
||||
const arr = [1, 2, 3, 4, 5];
|
||||
|
||||
return [{
|
||||
json: {
|
||||
mapped: arr.map(x => x * 2), // [2, 4, 6, 8, 10]
|
||||
filtered: arr.filter(x => x > 2), // [3, 4, 5]
|
||||
reduced: arr.reduce((sum, x) => sum + x, 0), // 15
|
||||
some: arr.some(x => x > 3), // true
|
||||
every: arr.every(x => x > 0), // true
|
||||
find: arr.find(x => x > 3), // 4
|
||||
includes: arr.includes(3), // true
|
||||
joined: arr.join(', ') // "1, 2, 3, 4, 5"
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Available Node.js Modules
|
||||
|
||||
### crypto Module
|
||||
|
||||
> **Gated**: `require('crypto')` only works if `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` (or legacy `NODE_FUNCTION_ALLOW_BUILTIN`) includes `crypto` (or is `*`). On default installs it throws "Cannot find module 'crypto'". For hashing you control, prefer doing it before reaching the Code node, or — if you must — verify your instance's config first.
|
||||
|
||||
```javascript
|
||||
const crypto = require('crypto');
|
||||
|
||||
// Hash functions
|
||||
const hash = crypto.createHash('sha256')
|
||||
.update('my secret text')
|
||||
.digest('hex');
|
||||
|
||||
// MD5 hash
|
||||
const md5 = crypto.createHash('md5')
|
||||
.update('my text')
|
||||
.digest('hex');
|
||||
|
||||
// Random values
|
||||
const randomBytes = crypto.randomBytes(16).toString('hex');
|
||||
|
||||
return [{json: {hash, md5, randomBytes}}];
|
||||
```
|
||||
|
||||
### Buffer (built-in)
|
||||
|
||||
```javascript
|
||||
// Base64 encoding
|
||||
const encoded = Buffer.from('Hello World').toString('base64');
|
||||
|
||||
// Base64 decoding
|
||||
const decoded = Buffer.from(encoded, 'base64').toString();
|
||||
|
||||
// Hex encoding
|
||||
const hex = Buffer.from('Hello').toString('hex');
|
||||
|
||||
return [{json: {encoded, decoded, hex}}];
|
||||
```
|
||||
|
||||
### URL / URLSearchParams
|
||||
|
||||
```javascript
|
||||
// Parse URL
|
||||
const url = new URL('https://example.com/path?param1=value1¶m2=value2');
|
||||
|
||||
// Build query string
|
||||
const params = new URLSearchParams({
|
||||
search: 'query',
|
||||
page: 1,
|
||||
limit: 10
|
||||
});
|
||||
|
||||
return [{
|
||||
json: {
|
||||
host: url.host,
|
||||
pathname: url.pathname,
|
||||
search: url.search,
|
||||
queryString: params.toString() // "search=query&page=1&limit=10"
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What's NOT Available
|
||||
|
||||
**External npm packages are NOT available** (unless explicitly allowlisted via `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` *and* installed in the runner image — rare):
|
||||
- ❌ axios
|
||||
- ❌ lodash
|
||||
- ❌ moment (use DateTime/Luxon instead)
|
||||
- ❌ request
|
||||
- ❌ Any other npm package
|
||||
|
||||
**Authentication helpers are blocked** in the task runner sandbox (see section 0):
|
||||
- ❌ `this.helpers.httpRequestWithAuthentication`
|
||||
- ❌ `this.helpers.requestWithAuthenticationPaginated`
|
||||
|
||||
**Conditionally blocked** (depends on instance config):
|
||||
- ⚠️ `$env.*` — blocked when `N8N_BLOCK_ENV_ACCESS_IN_NODE=true`
|
||||
- ⚠️ `require('crypto')` / `require('fs')` / etc. — blocked unless `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` includes them
|
||||
|
||||
**Workarounds**:
|
||||
- HTTP with auth → HTTP Request node with credential attached, or sub-workflow pattern
|
||||
- Secrets → arrive as data from an upstream HTTP Request / credential-aware node
|
||||
- Hashing/crypto → do it in a service the workflow calls, or get your instance config updated
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Most Useful Built-ins**:
|
||||
1. **this.helpers.httpRequest()** - API calls without HTTP Request node (the bare `$helpers` global is undefined)
|
||||
2. **DateTime** - Professional date/time handling
|
||||
3. **$jmespath()** - Complex JSON queries
|
||||
4. **Math, JSON, Object, Array** - Standard JavaScript utilities
|
||||
|
||||
**Common Patterns**:
|
||||
- API calls: Use this.helpers.httpRequest() (or, preferably, the HTTP Request node)
|
||||
- Date operations: Use DateTime (Luxon)
|
||||
- Data filtering: Use $jmespath() or JavaScript .filter()
|
||||
- Persistent data: Use $getWorkflowStaticData()
|
||||
- Hashing: Use crypto module
|
||||
|
||||
**See Also**:
|
||||
- [SKILL.md](SKILL.md) - Overview
|
||||
- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Real usage examples
|
||||
- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Error prevention
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,897 @@
|
||||
# Data Access Patterns - JavaScript Code Node
|
||||
|
||||
Comprehensive guide to accessing data in n8n Code nodes using JavaScript.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
In n8n Code nodes, you access data from previous nodes using built-in variables and methods. Understanding which method to use is critical for correct workflow execution.
|
||||
|
||||
**Data Access Priority** (by common usage):
|
||||
1. **`$input.all()`** - Most common - Batch operations, aggregations
|
||||
2. **`$input.first()`** - Very common - Single item operations
|
||||
3. **`$input.item`** - Common - Each Item mode only
|
||||
4. **`$node["NodeName"].json`** - Specific node references
|
||||
5. **`$json`** - Direct current item (legacy, use `$input` instead)
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: $input.all() - Process All Items
|
||||
|
||||
**Usage**: Most common pattern for batch processing
|
||||
|
||||
**When to use:**
|
||||
- Processing multiple records
|
||||
- Aggregating data (sum, count, average)
|
||||
- Filtering arrays
|
||||
- Transforming datasets
|
||||
- Comparing items
|
||||
- Sorting or ranking
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// Get all items from previous node
|
||||
const allItems = $input.all();
|
||||
|
||||
// allItems is an array of objects like:
|
||||
// [
|
||||
// {json: {id: 1, name: "Alice"}},
|
||||
// {json: {id: 2, name: "Bob"}}
|
||||
// ]
|
||||
|
||||
console.log(`Received ${allItems.length} items`);
|
||||
|
||||
return allItems;
|
||||
```
|
||||
|
||||
### Example 1: Filter Active Items
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Filter only active items
|
||||
const activeItems = allItems.filter(item => item.json.status === 'active');
|
||||
|
||||
return activeItems;
|
||||
```
|
||||
|
||||
### Example 2: Transform All Items
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Map to new structure
|
||||
const transformed = allItems.map(item => ({
|
||||
json: {
|
||||
id: item.json.id,
|
||||
fullName: `${item.json.firstName} ${item.json.lastName}`,
|
||||
email: item.json.email,
|
||||
processedAt: new Date().toISOString()
|
||||
}
|
||||
}));
|
||||
|
||||
return transformed;
|
||||
```
|
||||
|
||||
### Example 3: Aggregate Data
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Calculate total
|
||||
const total = allItems.reduce((sum, item) => {
|
||||
return sum + (item.json.amount || 0);
|
||||
}, 0);
|
||||
|
||||
return [{
|
||||
json: {
|
||||
total,
|
||||
count: allItems.length,
|
||||
average: total / allItems.length
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 4: Sort and Limit
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Get top 5 by score
|
||||
const topFive = allItems
|
||||
.sort((a, b) => (b.json.score || 0) - (a.json.score || 0))
|
||||
.slice(0, 5);
|
||||
|
||||
return topFive.map(item => ({json: item.json}));
|
||||
```
|
||||
|
||||
### Example 5: Group By Category
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Group items by category
|
||||
const grouped = {};
|
||||
|
||||
for (const item of allItems) {
|
||||
const category = item.json.category || 'Uncategorized';
|
||||
|
||||
if (!grouped[category]) {
|
||||
grouped[category] = [];
|
||||
}
|
||||
|
||||
grouped[category].push(item.json);
|
||||
}
|
||||
|
||||
// Convert to array format
|
||||
return Object.entries(grouped).map(([category, items]) => ({
|
||||
json: {
|
||||
category,
|
||||
items,
|
||||
count: items.length
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### Example 6: Deduplicate by ID
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all();
|
||||
|
||||
// Remove duplicates by ID
|
||||
const seen = new Set();
|
||||
const unique = [];
|
||||
|
||||
for (const item of allItems) {
|
||||
const id = item.json.id;
|
||||
|
||||
if (!seen.has(id)) {
|
||||
seen.add(id);
|
||||
unique.push(item);
|
||||
}
|
||||
}
|
||||
|
||||
return unique;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: $input.first() - Get First Item
|
||||
|
||||
**Usage**: Very common for single-item operations
|
||||
|
||||
**When to use:**
|
||||
- Previous node returns single object
|
||||
- Working with API responses
|
||||
- Getting initial/first data point
|
||||
- Configuration or metadata access
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// Get first item from previous node
|
||||
const firstItem = $input.first();
|
||||
|
||||
// Access the JSON data
|
||||
const data = firstItem.json;
|
||||
|
||||
console.log('First item:', data);
|
||||
|
||||
return [{json: data}];
|
||||
```
|
||||
|
||||
### Example 1: Process Single API Response
|
||||
|
||||
```javascript
|
||||
// Get API response (typically single object)
|
||||
const response = $input.first().json;
|
||||
|
||||
// Extract what you need
|
||||
return [{
|
||||
json: {
|
||||
userId: response.data.user.id,
|
||||
userName: response.data.user.name,
|
||||
status: response.status,
|
||||
fetchedAt: new Date().toISOString()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 2: Transform Single Object
|
||||
|
||||
```javascript
|
||||
const data = $input.first().json;
|
||||
|
||||
// Transform structure
|
||||
return [{
|
||||
json: {
|
||||
id: data.id,
|
||||
contact: {
|
||||
email: data.email,
|
||||
phone: data.phone
|
||||
},
|
||||
address: {
|
||||
street: data.street,
|
||||
city: data.city,
|
||||
zip: data.zip
|
||||
}
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 3: Validate Single Item
|
||||
|
||||
```javascript
|
||||
const item = $input.first().json;
|
||||
|
||||
// Validation logic
|
||||
const isValid = item.email && item.email.includes('@');
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...item,
|
||||
valid: isValid,
|
||||
validatedAt: new Date().toISOString()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 4: Extract Nested Data
|
||||
|
||||
```javascript
|
||||
const response = $input.first().json;
|
||||
|
||||
// Navigate nested structure
|
||||
const users = response.data?.users || [];
|
||||
|
||||
return users.map(user => ({
|
||||
json: {
|
||||
id: user.id,
|
||||
name: user.profile?.name || 'Unknown',
|
||||
email: user.contact?.email || 'no-email'
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### Example 5: Combine with Other Methods
|
||||
|
||||
```javascript
|
||||
// Get first item's data
|
||||
const firstData = $input.first().json;
|
||||
|
||||
// Use it to filter all items
|
||||
const allItems = $input.all();
|
||||
const matching = allItems.filter(item =>
|
||||
item.json.category === firstData.targetCategory
|
||||
);
|
||||
|
||||
return matching;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: $input.item - Current Item (Each Item Mode)
|
||||
|
||||
**Usage**: Common in "Run Once for Each Item" mode
|
||||
|
||||
**When to use:**
|
||||
- Mode is set to "Run Once for Each Item"
|
||||
- Need to process items independently
|
||||
- Per-item API calls or validations
|
||||
- Item-specific error handling
|
||||
|
||||
**IMPORTANT**: Only use in "Each Item" mode. Will be undefined in "All Items" mode.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// In "Run Once for Each Item" mode
|
||||
const currentItem = $input.item;
|
||||
const data = currentItem.json;
|
||||
|
||||
console.log('Processing item:', data.id);
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...data,
|
||||
processed: true
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 1: Add Processing Metadata
|
||||
|
||||
```javascript
|
||||
const item = $input.item;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...item.json,
|
||||
processed: true,
|
||||
processedAt: new Date().toISOString(),
|
||||
processingDuration: Math.random() * 1000 // Simulated duration
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 2: Per-Item Validation
|
||||
|
||||
```javascript
|
||||
const item = $input.item;
|
||||
const data = item.json;
|
||||
|
||||
// Validate this specific item
|
||||
const errors = [];
|
||||
|
||||
if (!data.email) errors.push('Email required');
|
||||
if (!data.name) errors.push('Name required');
|
||||
if (data.age && data.age < 18) errors.push('Must be 18+');
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...data,
|
||||
valid: errors.length === 0,
|
||||
errors: errors.length > 0 ? errors : undefined
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 3: Item-Specific API Call
|
||||
|
||||
```javascript
|
||||
const item = $input.item;
|
||||
const userId = item.json.userId;
|
||||
|
||||
// Make API call specific to this item
|
||||
const response = await this.helpers.httpRequest({
|
||||
method: 'GET',
|
||||
url: `https://api.example.com/users/${userId}/details`
|
||||
});
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...item.json,
|
||||
details: response
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
> ⚠️ **Use `this.helpers.httpRequest`, not `$helpers`.** In the Code node's task-runner sandbox (default since n8n v2.0) the bare `$helpers` global is undefined — `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`. **For authenticated APIs, don't extend this pattern.** `this.helpers.httpRequestWithAuthentication` is blocked in the task-runner sandbox. Use an HTTP Request node with the credential attached, or delegate to a sub-workflow whose HTTP Request node holds the credential. For anything beyond a trivial unauthenticated GET, prefer the HTTP Request node anyway. See ERROR_PATTERNS.md Error #6.
|
||||
|
||||
### Example 4: Conditional Processing
|
||||
|
||||
```javascript
|
||||
const item = $input.item;
|
||||
const data = item.json;
|
||||
|
||||
// Process based on item type
|
||||
if (data.type === 'premium') {
|
||||
return [{
|
||||
json: {
|
||||
...data,
|
||||
discount: 0.20,
|
||||
tier: 'premium'
|
||||
}
|
||||
}];
|
||||
} else {
|
||||
return [{
|
||||
json: {
|
||||
...data,
|
||||
discount: 0.05,
|
||||
tier: 'standard'
|
||||
}
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: $node - Reference Other Nodes
|
||||
|
||||
**Usage**: Less common, but powerful for specific scenarios
|
||||
|
||||
**When to use:**
|
||||
- Need data from specific named node
|
||||
- Combining data from multiple nodes
|
||||
- Accessing metadata about workflow execution
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```javascript
|
||||
// Get output from specific node
|
||||
const webhookData = $node["Webhook"].json;
|
||||
const apiData = $node["HTTP Request"].json;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
fromWebhook: webhookData,
|
||||
fromAPI: apiData
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 1: Combine Multiple Sources
|
||||
|
||||
```javascript
|
||||
// Reference multiple nodes
|
||||
const webhook = $node["Webhook"].json;
|
||||
const database = $node["Postgres"].json;
|
||||
const api = $node["HTTP Request"].json;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
combined: {
|
||||
webhook: webhook.body,
|
||||
dbRecords: database.length,
|
||||
apiResponse: api.status
|
||||
},
|
||||
processedAt: new Date().toISOString()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 2: Compare Across Nodes
|
||||
|
||||
```javascript
|
||||
const oldData = $node["Get Old Data"].json;
|
||||
const newData = $node["Get New Data"].json;
|
||||
|
||||
// Compare
|
||||
const changes = {
|
||||
added: newData.filter(n => !oldData.find(o => o.id === n.id)),
|
||||
removed: oldData.filter(o => !newData.find(n => n.id === o.id)),
|
||||
modified: newData.filter(n => {
|
||||
const old = oldData.find(o => o.id === n.id);
|
||||
return old && JSON.stringify(old) !== JSON.stringify(n);
|
||||
})
|
||||
};
|
||||
|
||||
return [{
|
||||
json: {
|
||||
changes,
|
||||
summary: {
|
||||
added: changes.added.length,
|
||||
removed: changes.removed.length,
|
||||
modified: changes.modified.length
|
||||
}
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Example 3: Access Node Metadata
|
||||
|
||||
```javascript
|
||||
// Get data from specific execution path
|
||||
const ifTrueBranch = $node["IF True"].json;
|
||||
const ifFalseBranch = $node["IF False"].json;
|
||||
|
||||
// Use whichever branch executed
|
||||
const result = ifTrueBranch || ifFalseBranch || {};
|
||||
|
||||
return [{json: result}];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical: Webhook Data Structure
|
||||
|
||||
**MOST COMMON MISTAKE**: Forgetting webhook data is nested under `.body`
|
||||
|
||||
### The Problem
|
||||
|
||||
Webhook node wraps all incoming data under a `body` property. This catches many developers by surprise.
|
||||
|
||||
### Structure
|
||||
|
||||
```javascript
|
||||
// Webhook node output structure:
|
||||
{
|
||||
"headers": {
|
||||
"content-type": "application/json",
|
||||
"user-agent": "...",
|
||||
// ... other headers
|
||||
},
|
||||
"params": {},
|
||||
"query": {},
|
||||
"body": {
|
||||
// ← YOUR DATA IS HERE
|
||||
"name": "Alice",
|
||||
"email": "alice@example.com",
|
||||
"message": "Hello!"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Wrong vs Right
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: Trying to access directly
|
||||
const name = $json.name; // undefined
|
||||
const email = $json.email; // undefined
|
||||
|
||||
// ✅ CORRECT: Access via .body
|
||||
const name = $json.body.name; // "Alice"
|
||||
const email = $json.body.email; // "alice@example.com"
|
||||
|
||||
// ✅ CORRECT: Extract body first
|
||||
const webhookData = $json.body;
|
||||
const name = webhookData.name; // "Alice"
|
||||
const email = webhookData.email; // "alice@example.com"
|
||||
```
|
||||
|
||||
### Example: Full Webhook Processing
|
||||
|
||||
```javascript
|
||||
// Get webhook data from previous node
|
||||
const webhookOutput = $input.first().json;
|
||||
|
||||
// Access the actual payload
|
||||
const payload = webhookOutput.body;
|
||||
|
||||
// Access headers if needed
|
||||
const contentType = webhookOutput.headers['content-type'];
|
||||
|
||||
// Access query parameters if needed
|
||||
const apiKey = webhookOutput.query.api_key;
|
||||
|
||||
// Process the actual data
|
||||
return [{
|
||||
json: {
|
||||
// Data from webhook body
|
||||
userName: payload.name,
|
||||
userEmail: payload.email,
|
||||
message: payload.message,
|
||||
|
||||
// Metadata
|
||||
receivedAt: new Date().toISOString(),
|
||||
contentType: contentType,
|
||||
authenticated: !!apiKey
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### POST Data, Query Params, and Headers
|
||||
|
||||
```javascript
|
||||
const webhook = $input.first().json;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
// POST body data
|
||||
formData: webhook.body,
|
||||
|
||||
// Query parameters (?key=value)
|
||||
queryParams: webhook.query,
|
||||
|
||||
// HTTP headers
|
||||
userAgent: webhook.headers['user-agent'],
|
||||
contentType: webhook.headers['content-type'],
|
||||
|
||||
// Request metadata
|
||||
method: webhook.method, // POST, GET, etc.
|
||||
url: webhook.url
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Common Webhook Scenarios
|
||||
|
||||
```javascript
|
||||
// Scenario 1: Form submission
|
||||
const formData = $json.body;
|
||||
const name = formData.name;
|
||||
const email = formData.email;
|
||||
|
||||
// Scenario 2: JSON API webhook
|
||||
const apiPayload = $json.body;
|
||||
const eventType = apiPayload.event;
|
||||
const data = apiPayload.data;
|
||||
|
||||
// Scenario 3: Query parameters
|
||||
const apiKey = $json.query.api_key;
|
||||
const userId = $json.query.user_id;
|
||||
|
||||
// Scenario 4: Headers
|
||||
const authorization = $json.headers['authorization'];
|
||||
const signature = $json.headers['x-signature'];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Choosing the Right Pattern
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
Do you need ALL items from previous node?
|
||||
├─ YES → Use $input.all()
|
||||
│
|
||||
└─ NO → Do you need just the FIRST item?
|
||||
├─ YES → Use $input.first()
|
||||
│
|
||||
└─ NO → Are you in "Each Item" mode?
|
||||
├─ YES → Use $input.item
|
||||
│
|
||||
└─ NO → Do you need specific node data?
|
||||
├─ YES → Use $node["NodeName"]
|
||||
└─ NO → Use $input.first() (default)
|
||||
```
|
||||
|
||||
### Quick Reference Table
|
||||
|
||||
| Scenario | Use This | Example |
|
||||
|----------|----------|---------|
|
||||
| Sum all amounts | `$input.all()` | `allItems.reduce((sum, i) => sum + i.json.amount, 0)` |
|
||||
| Get API response | `$input.first()` | `$input.first().json.data` |
|
||||
| Process each independently | `$input.item` | `$input.item.json` (Each Item mode) |
|
||||
| Combine two nodes | `$node["Name"]` | `$node["API"].json` |
|
||||
| Filter array | `$input.all()` | `allItems.filter(i => i.json.active)` |
|
||||
| Transform single object | `$input.first()` | `{...input.first().json, new: true}` |
|
||||
| Webhook data | `$input.first()` | `$input.first().json.body` |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Mistake 1: Using $json Without Context
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: $json is ambiguous
|
||||
const value = $json.field;
|
||||
|
||||
// ✅ CORRECT: Be explicit
|
||||
const value = $input.first().json.field;
|
||||
```
|
||||
|
||||
### Mistake 2: Forgetting .json Property
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: Trying to access fields on item object
|
||||
const items = $input.all();
|
||||
const names = items.map(item => item.name); // undefined
|
||||
|
||||
// ✅ CORRECT: Access via .json
|
||||
const names = items.map(item => item.json.name);
|
||||
```
|
||||
|
||||
### Mistake 3: Using $input.item in All Items Mode
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: $input.item is undefined in "All Items" mode
|
||||
const data = $input.item.json; // Error!
|
||||
|
||||
// ✅ CORRECT: Use appropriate method
|
||||
const data = $input.first().json; // Or $input.all()
|
||||
```
|
||||
|
||||
### Mistake 4: Not Handling Empty Arrays
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: Crashes if no items
|
||||
const first = $input.all()[0].json;
|
||||
|
||||
// ✅ CORRECT: Check length first
|
||||
const items = $input.all();
|
||||
if (items.length === 0) {
|
||||
return [];
|
||||
}
|
||||
const first = items[0].json;
|
||||
|
||||
// ✅ ALSO CORRECT: Use $input.first()
|
||||
const first = $input.first().json; // Built-in safety
|
||||
```
|
||||
|
||||
### Mistake 5: Modifying Original Data
|
||||
|
||||
```javascript
|
||||
// ❌ RISKY: Mutating original
|
||||
const items = $input.all();
|
||||
items[0].json.modified = true; // Modifies original
|
||||
return items;
|
||||
|
||||
// ✅ SAFE: Create new objects
|
||||
const items = $input.all();
|
||||
return items.map(item => ({
|
||||
json: {
|
||||
...item.json,
|
||||
modified: true
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Pattern: Pagination Handling
|
||||
|
||||
```javascript
|
||||
const currentPage = $input.all();
|
||||
const pageNumber = $node["Set Page"].json.page || 1;
|
||||
|
||||
// Combine with previous pages
|
||||
const allPreviousPages = $node["Accumulator"]?.json.accumulated || [];
|
||||
|
||||
return [{
|
||||
json: {
|
||||
accumulated: [...allPreviousPages, ...currentPage],
|
||||
currentPage: pageNumber,
|
||||
totalItems: allPreviousPages.length + currentPage.length
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Pattern: Conditional Node Reference
|
||||
|
||||
```javascript
|
||||
// Access different nodes based on condition
|
||||
const condition = $input.first().json.type;
|
||||
|
||||
let data;
|
||||
if (condition === 'api') {
|
||||
data = $node["API Response"].json;
|
||||
} else if (condition === 'database') {
|
||||
data = $node["Database"].json;
|
||||
} else {
|
||||
data = $node["Default"].json;
|
||||
}
|
||||
|
||||
return [{json: data}];
|
||||
```
|
||||
|
||||
### Pattern: Multi-Node Aggregation
|
||||
|
||||
```javascript
|
||||
// Collect data from multiple named nodes
|
||||
const sources = ['Source1', 'Source2', 'Source3'];
|
||||
const allData = [];
|
||||
|
||||
for (const source of sources) {
|
||||
const nodeData = $node[source]?.json;
|
||||
if (nodeData) {
|
||||
allData.push({
|
||||
source,
|
||||
data: nodeData
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return allData.map(item => ({json: item}));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Most Common Patterns**:
|
||||
1. `$input.all()` - Process multiple items, batch operations
|
||||
2. `$input.first()` - Single item, API responses
|
||||
3. `$input.item` - Each Item mode processing
|
||||
|
||||
**Critical Rule**:
|
||||
- Webhook data is under `.body` property
|
||||
|
||||
**Best Practice**:
|
||||
- Be explicit: Use `$input.first().json.field` instead of `$json.field`
|
||||
- Always check for null/undefined
|
||||
- Use appropriate method for your mode (All Items vs Each Item)
|
||||
|
||||
**See Also**:
|
||||
- [SKILL.md](SKILL.md) - Overview and quick start
|
||||
- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Production patterns
|
||||
- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Avoid common mistakes
|
||||
|
||||
---
|
||||
|
||||
## Mode Performance: Why "All Items" Is Faster
|
||||
|
||||
Mode choice is the single biggest performance lever in a Code node, and the reason generalizes to the rest of your workflow. Every time n8n hands items to a *per-item* execution context it pays a setup cost. Measured on an n8n 2.x instance (small records, ~10k items):
|
||||
|
||||
| What runs per item | Approx. cost | Why |
|
||||
|---|---|---|
|
||||
| Code **All Items** (one run for the whole set) | ~0.02 ms/item | one context setup, then plain JS — the loop is free |
|
||||
| Expression in any node (IF / Set / etc.) | ~0.2 ms/item | a light eval context per item |
|
||||
| Code **Each Item** | ~0.6 ms/item | a full code sandbox per item — ~3× an expression, ~25–30× All Items |
|
||||
|
||||
So `Run Once for Each Item` over 10k items is ~6 s of pure overhead vs ~0.2 s for the same logic in `Run Once for All Items`. Use Each Item only when an item genuinely needs isolating (independent error handling, or a per-item API call you can't batch); otherwise loop *inside* one All Items node.
|
||||
|
||||
Two corollaries you will hit constantly:
|
||||
|
||||
- **Expression complexity is essentially free.** An elaborate `{{ }}` measures the same as a trivial one — ~90% of the cost is n8n building the per-item context, not running your code. Don't simplify expressions for speed; reduce the *number* of per-item boundaries instead.
|
||||
- **Every node→node hop re-copies all items** (~0.05 ms/item per hop). Six chained All Items Code nodes cost ~7× a single node doing the same six steps, so consolidate a hot transform chain into one All Items node — and never build a chain of *Each Item* Code nodes, where the per-item tax multiplies by node count (a 6-node Each-Item chain over 2k items ≈ 7 s).
|
||||
|
||||
**Scale check:** below a few hundred items this is all sub-100 ms and not worth a thought, and most real workflows are dominated by I/O (HTTP / DB / Sheets round-trips) that dwarfs node overhead. Reach for these rules on the hot path — large item counts with little I/O — not everywhere.
|
||||
|
||||
---
|
||||
|
||||
## Production Gotchas
|
||||
|
||||
Hard-won lessons from real-world n8n workflow deployments.
|
||||
|
||||
### SplitInBatches Loop Semantics
|
||||
|
||||
The SplitInBatches node has two outputs — and the naming is counterintuitive:
|
||||
- `main[0]` = **done** — fires ONCE after all batches are processed
|
||||
- `main[1]` = **each batch** — fires for every batch (this is the loop body)
|
||||
|
||||
Always add a **Limit 1** node after the done output before downstream processing, as a safety against edge cases where done fires with extra items.
|
||||
|
||||
### SplitInBatches: Iteration Count Is the Cost
|
||||
|
||||
Each loop iteration re-executes the entire loop body through the workflow engine — ~0.8 ms per iteration of pure overhead, on top of whatever the body does. Total ≈ `⌈items / batchSize⌉ × (~0.8 ms + body cost)`:
|
||||
|
||||
- `batchSize: 1` over N items pays that N times — it's the loop equivalent of *Run Once for Each Item* (and if the body has several nodes, each iteration re-pays all of them).
|
||||
- Raising `batchSize` cuts iterations proportionally; the body still sees every item. Use the **largest batch your real constraint allows** (API rate limit, page size, memory). If you don't need batching at all, don't loop — process the whole set in one All Items node.
|
||||
|
||||
### Cross-Iteration Data Accumulation (CRITICAL)
|
||||
|
||||
After a SplitInBatches loop, `$('Node Inside Loop').all()` returns **ONLY the last iteration's items**, not cumulative results. This silently drops data from all but the final batch.
|
||||
|
||||
**Fix**: Use workflow static data to accumulate across iterations:
|
||||
|
||||
```javascript
|
||||
// BEFORE the loop (reset accumulator):
|
||||
const staticData = $getWorkflowStaticData('global');
|
||||
staticData.results = [];
|
||||
return $input.all();
|
||||
|
||||
// INSIDE the loop body (accumulate):
|
||||
const staticData = $getWorkflowStaticData('global');
|
||||
const results = [];
|
||||
for (const item of $input.all()) {
|
||||
const processed = { /* ... */ };
|
||||
results.push({ json: processed });
|
||||
staticData.results.push(processed);
|
||||
}
|
||||
return results;
|
||||
|
||||
// AFTER the loop (read accumulated data):
|
||||
const staticData = $getWorkflowStaticData('global');
|
||||
const allResults = staticData.results || [];
|
||||
// Now aggregate across ALL iterations
|
||||
```
|
||||
|
||||
### pairedItem for New Output Items
|
||||
|
||||
When creating new items that don't map 1:1 to input items, include `pairedItem` — otherwise downstream Set nodes fail with `paired_item_no_info`:
|
||||
|
||||
```javascript
|
||||
const results = [];
|
||||
for (let i = 0; i < $input.all().length; i++) {
|
||||
const item = $input.all()[i];
|
||||
results.push({
|
||||
json: { /* new data */ },
|
||||
pairedItem: { item: i }
|
||||
});
|
||||
}
|
||||
return results;
|
||||
```
|
||||
|
||||
### Correct Node Reference Syntax
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG - .json directly on node reference
|
||||
const data = $('HTTP Request').json;
|
||||
|
||||
// ✅ CORRECT - call .first() then access .json
|
||||
const data = $('HTTP Request').first().json;
|
||||
|
||||
// ✅ Also correct - get all items
|
||||
const allData = $('HTTP Request').all();
|
||||
```
|
||||
|
||||
### Float Precision for Price/Currency Comparison
|
||||
|
||||
When comparing prices or currency values, floating point noise can cause false positives. Round to cents:
|
||||
|
||||
```javascript
|
||||
// ❌ Unreliable - float comparison
|
||||
if (newPrice !== oldPrice) { /* triggers on noise */ }
|
||||
|
||||
// ✅ Reliable - compare at cent level
|
||||
if (Math.round(newPrice * 100) !== Math.round(oldPrice * 100)) {
|
||||
// Real price change detected
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,857 @@
|
||||
# Error Patterns - JavaScript Code Node
|
||||
|
||||
Complete guide to avoiding the most common Code node errors.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers the **top 5 error patterns** encountered in n8n Code nodes. Understanding and avoiding these errors will save you significant debugging time.
|
||||
|
||||
**Error frequency (roughly ordered)**:
|
||||
1. Empty Code / Missing Return - the dominant error n8n itself rejects
|
||||
2. Expression Syntax used as Code - `{{ }}` written where JavaScript belongs
|
||||
3. Return Shape - primitive/`null` returns (bare objects auto-wrap)
|
||||
4. Broken Strings / Escaping - unbalanced quotes/brackets throw a JS syntax error
|
||||
5. Missing Null Checks - common runtime error
|
||||
|
||||
---
|
||||
|
||||
## Error #1: Empty Code or Missing Return Statement
|
||||
|
||||
**Frequency**: Most common error (38% of all validation failures)
|
||||
|
||||
**What Happens**:
|
||||
- Workflow execution fails
|
||||
- Next nodes receive no data
|
||||
- Error: "Code cannot be empty" or "Code must return data"
|
||||
|
||||
### The Problem
|
||||
|
||||
```javascript
|
||||
// ❌ ERROR: No code at all
|
||||
// (Empty code field)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ ERROR: Code executes but doesn't return anything
|
||||
const items = $input.all();
|
||||
|
||||
// Process items
|
||||
for (const item of items) {
|
||||
console.log(item.json.name);
|
||||
}
|
||||
|
||||
// Forgot to return!
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ ERROR: Early return path exists, but not all paths return
|
||||
const items = $input.all();
|
||||
|
||||
if (items.length === 0) {
|
||||
return []; // ✅ This path returns
|
||||
}
|
||||
|
||||
// Process items
|
||||
const processed = items.map(item => ({json: item.json}));
|
||||
|
||||
// ❌ Forgot to return processed!
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Always return data
|
||||
const items = $input.all();
|
||||
|
||||
// Process items
|
||||
const processed = items.map(item => ({
|
||||
json: {
|
||||
...item.json,
|
||||
processed: true
|
||||
}
|
||||
}));
|
||||
|
||||
return processed; // ✅ Return statement present
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Return empty array if no items
|
||||
const items = $input.all();
|
||||
|
||||
if (items.length === 0) {
|
||||
return []; // Valid: empty array when no data
|
||||
}
|
||||
|
||||
// Process and return
|
||||
return items.map(item => ({json: item.json}));
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: All code paths return
|
||||
const items = $input.all();
|
||||
|
||||
if (items.length === 0) {
|
||||
return [];
|
||||
} else if (items.length === 1) {
|
||||
return [{json: {single: true, data: items[0].json}}];
|
||||
} else {
|
||||
return items.map(item => ({json: item.json}));
|
||||
}
|
||||
|
||||
// All paths covered
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] Code field is not empty
|
||||
- [ ] Return statement exists
|
||||
- [ ] ALL code paths return data (if/else branches)
|
||||
- [ ] Return format is correct (`[{json: {...}}]`)
|
||||
- [ ] Return happens even on errors (use try-catch)
|
||||
|
||||
---
|
||||
|
||||
## Error #2: Expression Syntax Confusion
|
||||
|
||||
**What Happens** — there are two distinct cases, and only one is a syntax error:
|
||||
- **`{{ }}` inside a string literal**: valid JavaScript that runs fine, but you get the *literal text* `{{ ... }}` instead of a value — n8n does not evaluate expressions inside Code-node code. A logic bug, not a validation error. (n8n-mcp ≥ 2.63.0 no longer flags `{{ }}` inside string literals — prompt templates, payload placeholders, and `.replace()` tokens are legitimate.)
|
||||
- **`{{ }}` written as bare code** (e.g. `return {{ $json.x }}`): a genuine JavaScript syntax error. The validator reports "Expression syntax {{...}} is not valid in Code nodes" and n8n throws "Unexpected token".
|
||||
|
||||
### The Problem
|
||||
|
||||
n8n has TWO distinct syntaxes:
|
||||
1. **Expression syntax** `{{ }}` - Used in OTHER nodes (Set, IF, HTTP Request)
|
||||
2. **JavaScript** - Used in CODE nodes
|
||||
|
||||
Many developers mistakenly reach for expression syntax inside a Code node when they want a *value*. Putting `{{ }}` in a string does not interpolate it:
|
||||
|
||||
```javascript
|
||||
// ❌ LOGIC BUG: n8n never evaluates {{ }} in Code-node strings
|
||||
const userName = "{{ $json.name }}";
|
||||
const userEmail = "{{ $json.body.email }}";
|
||||
|
||||
return [{
|
||||
json: {
|
||||
name: userName,
|
||||
email: userEmail
|
||||
}
|
||||
}];
|
||||
|
||||
// Result: Literal string "{{ $json.name }}", NOT the value!
|
||||
// (This runs — it just doesn't do what you meant. Use $json.name directly.)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ SYNTAX ERROR: {{ }} used as code, not inside a string
|
||||
const value = {{ $now.toFormat('yyyy-MM-dd') }}; // "Unexpected token"
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Use JavaScript directly (no {{ }})
|
||||
const userName = $json.name;
|
||||
const userEmail = $json.body.email;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
name: userName,
|
||||
email: userEmail
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: JavaScript template literals (use backticks)
|
||||
const message = `Hello, ${$json.name}! Your email is ${$json.email}`;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
greeting: message
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Direct variable access
|
||||
const item = $input.first().json;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
name: item.name,
|
||||
email: item.email,
|
||||
timestamp: new Date().toISOString() // JavaScript Date, not {{ }}
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
### Comparison Table
|
||||
|
||||
| Context | Syntax | Example |
|
||||
|---------|--------|---------|
|
||||
| Set node | `{{ }}` expressions | `{{ $json.name }}` |
|
||||
| IF node | `{{ }}` expressions | `{{ $json.age > 18 }}` |
|
||||
| HTTP Request URL | `{{ }}` expressions | `{{ $json.userId }}` |
|
||||
| **Code node** | **JavaScript** | `$json.name` |
|
||||
| **Code node strings** | **Template literals** | `` `Hello ${$json.name}` `` |
|
||||
|
||||
### Quick Fix Guide
|
||||
|
||||
```javascript
|
||||
// WRONG → RIGHT conversions
|
||||
|
||||
// ❌ "{{ $json.field }}"
|
||||
// ✅ $json.field
|
||||
|
||||
// ❌ "{{ $now }}"
|
||||
// ✅ new Date().toISOString()
|
||||
|
||||
// ❌ "{{ $node['HTTP Request'].json.data }}"
|
||||
// ✅ $node["HTTP Request"].json.data
|
||||
|
||||
// ❌ `{{ $json.firstName }} {{ $json.lastName }}`
|
||||
// ✅ `${$json.firstName} ${$json.lastName}`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error #3: Return Shape
|
||||
|
||||
**What actually happens** — n8n is more forgiving than the old advice implied:
|
||||
- In *Run Once for All Items* mode, n8n **auto-normalizes** a single bare object, or an array of bare objects, by wrapping each under a `json` property. So these run.
|
||||
- What genuinely fails, with "Code doesn't return items properly", is returning a **primitive** (string/number/boolean) or **`null`/`undefined`** — there is nothing to wrap.
|
||||
|
||||
(n8n-mcp ≥ 2.63.0 no longer errors "Return value must be an array of objects" on a bare-object return; the earlier claim contradicted n8n's auto-wrap behavior.)
|
||||
|
||||
### Prefer the Canonical Form
|
||||
|
||||
The canonical `[{json: {...}}]` is unambiguous and behaves identically in both execution modes, so make it your default even though looser shapes are auto-wrapped:
|
||||
|
||||
```javascript
|
||||
// ⚠️ Auto-wrapped → [{json: {result: 'success'}}]. Runs, but prefer the array + json form.
|
||||
return {
|
||||
json: {
|
||||
result: 'success'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ⚠️ Auto-wrapped → each object gets a json wrapper. Runs, but be explicit.
|
||||
return [
|
||||
{id: 1, name: 'Alice'},
|
||||
{id: 2, name: 'Bob'}
|
||||
];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ Fine — input items already carry a json property; returning them unchanged is a valid passthrough
|
||||
return $input.all();
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ FAILS: primitive value — nothing to wrap into an item
|
||||
return "processed";
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ FAILS: null / undefined — no items to pass on
|
||||
return null;
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Single result
|
||||
return [{
|
||||
json: {
|
||||
result: 'success',
|
||||
timestamp: new Date().toISOString()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Multiple results
|
||||
return [
|
||||
{json: {id: 1, name: 'Alice'}},
|
||||
{json: {id: 2, name: 'Bob'}},
|
||||
{json: {id: 3, name: 'Carol'}}
|
||||
];
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Transforming array
|
||||
const items = $input.all();
|
||||
|
||||
return items.map(item => ({
|
||||
json: {
|
||||
id: item.json.id,
|
||||
name: item.json.name,
|
||||
processed: true
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Empty result
|
||||
return [];
|
||||
// Valid when no data to return
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Conditional returns
|
||||
if (shouldProcess) {
|
||||
return [{json: {result: 'processed'}}];
|
||||
} else {
|
||||
return [];
|
||||
}
|
||||
```
|
||||
|
||||
### Return Format Checklist
|
||||
|
||||
- [ ] Return value is an **array** `[...]` (canonical — preferred)
|
||||
- [ ] Each array element has a **`json` property**
|
||||
- [ ] Structure is `[{json: {...}}]` or `[{json: {...}}, {json: {...}}]`
|
||||
- [ ] Not a primitive (string/number/boolean) or `null`/`undefined` — those are the shapes that actually fail
|
||||
|
||||
### Common Scenarios
|
||||
|
||||
```javascript
|
||||
// Scenario 1: Single object from API
|
||||
const response = $input.first().json;
|
||||
|
||||
// ✅ CANONICAL
|
||||
return [{json: response}];
|
||||
|
||||
// ⚠️ Auto-wrapped to the same thing — runs, but prefer the array form
|
||||
return {json: response};
|
||||
|
||||
|
||||
// Scenario 2: Array of objects
|
||||
const users = $input.all();
|
||||
|
||||
// ✅ CANONICAL
|
||||
return users.map(user => ({json: user.json}));
|
||||
|
||||
// ✅ Also fine — a passthrough of items that already carry json
|
||||
return users;
|
||||
|
||||
|
||||
// Scenario 3: Computed result
|
||||
const total = $input.all().reduce((sum, item) => sum + item.json.amount, 0);
|
||||
|
||||
// ✅ CANONICAL
|
||||
return [{json: {total}}];
|
||||
|
||||
// ⚠️ Auto-wrapped → [{json: {total}}] in All Items mode — runs, but be explicit
|
||||
return {total};
|
||||
|
||||
|
||||
// Scenario 4: No results
|
||||
// ✅ CORRECT
|
||||
return [];
|
||||
|
||||
// ❌ FAILS — null has no items to pass on
|
||||
return null;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error #4: Broken Strings & Escaping (JavaScript syntax errors)
|
||||
|
||||
**What Happens**:
|
||||
- The Code node throws a JavaScript syntax error at execution: "Unexpected token" or "Unexpected end of input"
|
||||
- Cause is your own JS — unbalanced quotes or a raw newline inside a plain quoted string
|
||||
|
||||
This is a plain JavaScript concern, **not** a validator check. The validator (n8n-mcp ≥ 2.63.0) does not flag balanced apostrophes, `{ }` in regex, or `{{ }}` sitting inside a string literal — those are all valid JavaScript. Only genuinely malformed JS throws, and it throws at runtime.
|
||||
|
||||
### The Problem
|
||||
|
||||
This happens when:
|
||||
1. A quote inside a same-quoted string is left unescaped
|
||||
2. A plain (non-template) string spans multiple lines
|
||||
3. Backslashes in paths/regex are not escaped
|
||||
|
||||
```javascript
|
||||
// ✅ FINE: an apostrophe inside a double-quoted string is valid JavaScript
|
||||
const message = "It's a nice day";
|
||||
|
||||
// ✅ FINE: braces in a regex literal are valid
|
||||
const pattern = /\{(\w+)\}/;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ SYNTAX ERROR: raw newline + unescaped inner double-quotes in a plain string
|
||||
const html = "
|
||||
<div class="container">
|
||||
<p>Hello</p>
|
||||
</div>
|
||||
";
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
```javascript
|
||||
// ✅ Mix quote styles or escape, whichever reads cleaner
|
||||
const message = "It's a nice day"; // double quotes around an apostrophe — fine
|
||||
const other = 'She said "hello"'; // single quotes around double quotes — fine
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ Regex literals need no extra escaping of their own braces
|
||||
const pattern = /\{(\w+)\}/;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Template literals for multi-line
|
||||
const html = `
|
||||
<div class="container">
|
||||
<p>Hello</p>
|
||||
</div>
|
||||
`;
|
||||
// Backticks handle multi-line and quotes
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Escape backslashes
|
||||
const path = "C:\\\\Users\\\\Documents\\\\file.txt";
|
||||
```
|
||||
|
||||
### Escaping Guide
|
||||
|
||||
| Character | Escape As | Example |
|
||||
|-----------|-----------|---------|
|
||||
| Single quote in single-quoted string | `\\'` | `'It\\'s working'` |
|
||||
| Double quote in double-quoted string | `\\"` | `"She said \\"hello\\""` |
|
||||
| Backslash | `\\\\` | `"C:\\\\path"` |
|
||||
| Newline | `\\n` | `"Line 1\\nLine 2"` |
|
||||
| Tab | `\\t` | `"Column1\\tColumn2"` |
|
||||
|
||||
### Best Practices
|
||||
|
||||
```javascript
|
||||
// ✅ BEST: Use template literals for complex strings
|
||||
const message = `User ${name} said: "Hello!"`;
|
||||
|
||||
// ✅ BEST: Use template literals for HTML
|
||||
const html = `
|
||||
<div class="${className}">
|
||||
<h1>${title}</h1>
|
||||
<p>${content}</p>
|
||||
</div>
|
||||
`;
|
||||
|
||||
// ✅ BEST: Use template literals for JSON
|
||||
const jsonString = `{
|
||||
"name": "${name}",
|
||||
"email": "${email}"
|
||||
}`;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error #5: Missing Null Checks / Undefined Access
|
||||
|
||||
**Frequency**: Very common runtime error
|
||||
|
||||
**What Happens**:
|
||||
- Workflow execution stops
|
||||
- Error: "Cannot read property 'X' of undefined"
|
||||
- Error: "Cannot read property 'X' of null"
|
||||
- Crashes on missing data
|
||||
|
||||
### The Problem
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: No null check - crashes if user doesn't exist
|
||||
const email = item.json.user.email;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: Assumes array has items
|
||||
const firstItem = $input.all()[0].json;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: Assumes nested property exists
|
||||
const city = $json.address.city;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG: No validation before array operations
|
||||
const names = $json.users.map(user => user.name);
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Optional chaining
|
||||
const email = item.json?.user?.email || 'no-email@example.com';
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Check array length
|
||||
const items = $input.all();
|
||||
|
||||
if (items.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const firstItem = items[0].json;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Guard clauses
|
||||
const data = $input.first().json;
|
||||
|
||||
if (!data.address) {
|
||||
return [{json: {error: 'No address provided'}}];
|
||||
}
|
||||
|
||||
const city = data.address.city;
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Default values
|
||||
const users = $json.users || [];
|
||||
const names = users.map(user => user.name || 'Unknown');
|
||||
```
|
||||
|
||||
```javascript
|
||||
// ✅ CORRECT: Try-catch for risky operations
|
||||
try {
|
||||
const email = item.json.user.email.toLowerCase();
|
||||
return [{json: {email}}];
|
||||
} catch (error) {
|
||||
return [{
|
||||
json: {
|
||||
error: 'Invalid user data',
|
||||
details: error.message
|
||||
}
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
### Safe Access Patterns
|
||||
|
||||
```javascript
|
||||
// Pattern 1: Optional chaining (modern, recommended)
|
||||
const value = data?.nested?.property?.value;
|
||||
|
||||
// Pattern 2: Logical OR with default
|
||||
const value = data.property || 'default';
|
||||
|
||||
// Pattern 3: Ternary check
|
||||
const value = data.property ? data.property : 'default';
|
||||
|
||||
// Pattern 4: Guard clause
|
||||
if (!data.property) {
|
||||
return [];
|
||||
}
|
||||
const value = data.property;
|
||||
|
||||
// Pattern 5: Try-catch
|
||||
try {
|
||||
const value = data.nested.property.value;
|
||||
} catch (error) {
|
||||
const value = 'default';
|
||||
}
|
||||
```
|
||||
|
||||
### Webhook Data Safety
|
||||
|
||||
```javascript
|
||||
// Webhook data requires extra safety
|
||||
|
||||
// ❌ RISKY: Assumes all fields exist
|
||||
const name = $json.body.user.name;
|
||||
const email = $json.body.user.email;
|
||||
|
||||
// ✅ SAFE: Check each level
|
||||
const body = $json.body || {};
|
||||
const user = body.user || {};
|
||||
const name = user.name || 'Unknown';
|
||||
const email = user.email || 'no-email';
|
||||
|
||||
// ✅ BETTER: Optional chaining
|
||||
const name = $json.body?.user?.name || 'Unknown';
|
||||
const email = $json.body?.user?.email || 'no-email';
|
||||
```
|
||||
|
||||
### Array Safety
|
||||
|
||||
```javascript
|
||||
// ❌ RISKY: No length check
|
||||
const items = $input.all();
|
||||
const firstId = items[0].json.id;
|
||||
|
||||
// ✅ SAFE: Check length
|
||||
const items = $input.all();
|
||||
|
||||
if (items.length > 0) {
|
||||
const firstId = items[0].json.id;
|
||||
} else {
|
||||
// Handle empty case
|
||||
return [];
|
||||
}
|
||||
|
||||
// ✅ BETTER: Use $input.first()
|
||||
const firstItem = $input.first();
|
||||
const firstId = firstItem.json.id; // Built-in safety
|
||||
```
|
||||
|
||||
### Object Property Safety
|
||||
|
||||
```javascript
|
||||
// ❌ RISKY: Direct access
|
||||
const config = $json.settings.advanced.timeout;
|
||||
|
||||
// ✅ SAFE: Step by step with defaults
|
||||
const settings = $json.settings || {};
|
||||
const advanced = settings.advanced || {};
|
||||
const timeout = advanced.timeout || 30000;
|
||||
|
||||
// ✅ BETTER: Optional chaining
|
||||
const timeout = $json.settings?.advanced?.timeout ?? 30000;
|
||||
// Note: ?? (nullish coalescing) vs || (logical OR)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error #6: UnsupportedFunctionError (Auth Helpers Blocked)
|
||||
|
||||
**Frequency**: The most common "this worked yesterday in old n8n" error after upgrading to v2.0+
|
||||
|
||||
**What Happens**:
|
||||
- Error: `UnsupportedFunctionError: The function "helpers.httpRequestWithAuthentication" is not supported in the Code Node`
|
||||
- Same for `helpers.requestWithAuthenticationPaginated`
|
||||
- Throws on execution, not on save
|
||||
|
||||
### The Problem
|
||||
|
||||
Since n8n v2.0, Code nodes execute in the **task runner sandbox** which deliberately blocks the auth helpers. The legacy vm2 sandbox used to bind them, which is why old forum posts and tutorials show them working. n8n's source comment explains why: the Code node has no credential of its own, so the helper had nothing to authenticate against — it was always semantically broken, just not always loud about it.
|
||||
|
||||
```javascript
|
||||
// ❌ BLOCKED in task runner sandbox (default since v2.0)
|
||||
const data = await this.helpers.httpRequestWithAuthentication.call(
|
||||
this,
|
||||
'baseLinkerApi',
|
||||
{ url: '...', method: 'POST' }
|
||||
);
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
There is **no env flag** to re-enable these in the runner — the deny-list is compiled-in. Pick one of:
|
||||
|
||||
**Option A — Replace the Code node with an HTTP Request node** (best):
|
||||
|
||||
The HTTP Request node natively supports credential attachment with full expression support for URL/body/headers. Most "Code-node-makes-an-API-call" patterns are leftovers from before HTTP Request had pagination and expression support.
|
||||
|
||||
**Option B — Sub-workflow with HTTP Request node** (when you need code-level logic before/after):
|
||||
|
||||
```javascript
|
||||
// Parent Code node — prepare payloads, then delegate
|
||||
return $input.all().map(i => ({ json: {
|
||||
url: 'https://api.example.com/things',
|
||||
method: 'POST',
|
||||
body: { sku: i.json.sku }
|
||||
}}));
|
||||
```
|
||||
|
||||
Then wire to **Execute Workflow** → child workflow with **Execute Workflow Trigger** → **HTTP Request** node using `={{ $json.url }}`, `={{ $json.body }}`, with the credential attached natively.
|
||||
|
||||
**Option C — Token as runtime data** (only when the token genuinely flows through the workflow):
|
||||
|
||||
```javascript
|
||||
// ✅ Works — manual auth header, token came from upstream
|
||||
const token = $('Get Token').first().json.access_token;
|
||||
|
||||
const data = await this.helpers.httpRequest({
|
||||
url: 'https://api.example.com/data',
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
});
|
||||
```
|
||||
|
||||
### Decision Guide
|
||||
|
||||
| Need | Use |
|
||||
|------|-----|
|
||||
| Single authenticated API call | HTTP Request node directly |
|
||||
| Many API calls + pre/post processing | Sub-workflow pattern (Option B) |
|
||||
| Token already in the data flow | Manual `this.helpers.httpRequest()` with header |
|
||||
| `httpRequestWithAuthentication` | **Doesn't work — pick A, B, or C above** |
|
||||
|
||||
---
|
||||
|
||||
## Error #7: $env is not defined / Cannot access $env
|
||||
|
||||
**Frequency**: Common in hardened production instances
|
||||
|
||||
**What Happens**:
|
||||
- Error: `$env is not defined` or `ReferenceError: $env is not defined`
|
||||
- Code looks correct, runs fine on dev instance, throws in production
|
||||
|
||||
### The Problem
|
||||
|
||||
`$env` access is gated by the **`N8N_BLOCK_ENV_ACCESS_IN_NODE`** environment variable. When set to `true` (a common production hardening setting), `$env` is removed from the Code node sandbox entirely. This is increasingly the default in security-conscious deployments.
|
||||
|
||||
```javascript
|
||||
// ❌ Throws if N8N_BLOCK_ENV_ACCESS_IN_NODE=true
|
||||
const apiKey = $env.API_KEY;
|
||||
```
|
||||
|
||||
### The Solution
|
||||
|
||||
Treat secrets as a **credential concern**, not a Code-node concern:
|
||||
|
||||
```javascript
|
||||
// ✅ Token arrives as data from an upstream node that used a credential
|
||||
const apiKey = $('Set Secret').first().json.apiKey;
|
||||
|
||||
// Or: secret was attached server-side by an HTTP Request node with the credential
|
||||
// — your Code node never sees the raw secret, which is the whole point
|
||||
```
|
||||
|
||||
For values you genuinely need to inject from outside the workflow (config, not secrets), use:
|
||||
- A **Set** node at the top of the workflow with hardcoded constants, or
|
||||
- An **n8n credential** referenced by an HTTP Request node, or
|
||||
- The **External Secrets** integration (`$secrets`) if your edition supports it.
|
||||
|
||||
### Why This Matters
|
||||
|
||||
Skills and tutorials written before 2024 routinely use `$env.API_KEY` because it was the path of least resistance. Modern n8n setups block it because letting Code nodes read arbitrary env vars is a privilege escalation surface — any user with workflow-edit access could exfiltrate `DB_PASSWORD`, `N8N_ENCRYPTION_KEY`, etc. Don't fight the restriction; route secrets through credentials.
|
||||
|
||||
---
|
||||
|
||||
## Error Prevention Checklist
|
||||
|
||||
Use this checklist before deploying Code nodes:
|
||||
|
||||
### Code Structure
|
||||
- [ ] Code field is not empty
|
||||
- [ ] Return statement exists
|
||||
- [ ] All code paths return data
|
||||
|
||||
### Return Format
|
||||
- [ ] Returns items, not a primitive/`null`
|
||||
- [ ] Canonical shape `[{json: {...}}]` (bare objects auto-wrap, but be explicit)
|
||||
|
||||
### Syntax
|
||||
- [ ] No `{{ }}` written as code (it's for other nodes' fields; in a string it's just literal text)
|
||||
- [ ] Template literals use backticks: `` `${variable}` ``
|
||||
- [ ] All quotes and brackets balanced
|
||||
- [ ] Strings properly escaped
|
||||
|
||||
### Data Safety
|
||||
- [ ] Null checks for optional properties
|
||||
- [ ] Array length checks before access
|
||||
- [ ] Webhook data accessed via `.body`
|
||||
- [ ] Try-catch for risky operations
|
||||
- [ ] Default values for missing data
|
||||
|
||||
### Testing
|
||||
- [ ] Test with empty input
|
||||
- [ ] Test with missing fields
|
||||
- [ ] Test with unexpected data types
|
||||
- [ ] Check browser console for errors
|
||||
|
||||
---
|
||||
|
||||
## Quick Error Reference
|
||||
|
||||
| Error Message | Likely Cause | Fix |
|
||||
|---------------|--------------|-----|
|
||||
| "Code cannot be empty" | Empty code field | Add meaningful code |
|
||||
| "Code must return data" | Missing return statement | Add `return [...]` |
|
||||
| "Code doesn't return items properly" | Returned a primitive (string/number) or `null` | Return `[{json:{...}}]` (objects/arrays auto-wrap; primitives don't) |
|
||||
| "Not all items have a json key" | Mixed return — some items wrapped, some bare | Wrap every item: `{json: {...}}` |
|
||||
| "Expression syntax {{...}} is not valid in Code nodes" / "Unexpected token" | `{{ }}` written as code (not inside a string) | Use JavaScript: `$json.x` or `` `${$json.x}` `` |
|
||||
| "Cannot read property X of undefined" | Missing null check | Use optional chaining `?.` |
|
||||
| "Cannot read property X of null" | Null value access | Add guard clause or default |
|
||||
| "Unexpected end of input" | Unbalanced quotes/brackets in your JS | Escape strings or use backtick template literals |
|
||||
| "UnsupportedFunctionError ... httpRequestWithAuthentication" | Auth helper blocked in task runner | Use HTTP Request node + credential, or sub-workflow pattern (Error #6) |
|
||||
| "$env is not defined" | `N8N_BLOCK_ENV_ACCESS_IN_NODE=true` | Route secrets through credentials, not `$env` (Error #7) |
|
||||
| "Cannot find module 'crypto'" | `require()` allowlist not set | Move logic out of Code node, or set `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` |
|
||||
|
||||
---
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### 1. Use console.log()
|
||||
|
||||
```javascript
|
||||
const items = $input.all();
|
||||
console.log('Items count:', items.length);
|
||||
console.log('First item:', items[0]);
|
||||
|
||||
// Check browser console (F12) for output
|
||||
```
|
||||
|
||||
### 2. Return Intermediate Results
|
||||
|
||||
```javascript
|
||||
// Debug by returning current state
|
||||
const items = $input.all();
|
||||
const processed = items.map(item => ({json: item.json}));
|
||||
|
||||
// Return to see what you have
|
||||
return processed;
|
||||
```
|
||||
|
||||
### 3. Try-Catch for Troubleshooting
|
||||
|
||||
```javascript
|
||||
try {
|
||||
// Your code here
|
||||
const result = riskyOperation();
|
||||
return [{json: {result}}];
|
||||
} catch (error) {
|
||||
// See what failed
|
||||
return [{
|
||||
json: {
|
||||
error: error.message,
|
||||
stack: error.stack
|
||||
}
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Validate Input Structure
|
||||
|
||||
```javascript
|
||||
const items = $input.all();
|
||||
|
||||
// Check what you received
|
||||
console.log('Input structure:', JSON.stringify(items[0], null, 2));
|
||||
|
||||
// Then process
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Top 7 Errors to Avoid**:
|
||||
1. **Empty code / missing return** - Always return data
|
||||
2. **Expression syntax as code** - Use JavaScript, not `{{ }}` (in-string `{{ }}` is just literal text)
|
||||
3. **Return shape** - prefer `[{json: {...}}]`; primitives/`null` fail (bare objects auto-wrap)
|
||||
4. **Broken strings** - unbalanced quotes/brackets throw a JS syntax error; escape or use template literals
|
||||
5. **Missing null checks** - Use optional chaining `?.`
|
||||
6. **`httpRequestWithAuthentication` blocked** - Use HTTP Request node + credential
|
||||
7. **`$env` blocked** - Route secrets through credentials, not env access
|
||||
|
||||
**Quick Prevention**:
|
||||
- Prefer the canonical `[{json: {...}}]` return; never return a primitive or `null`
|
||||
- Write JavaScript — don't put `{{ }}` where code belongs
|
||||
- Check for null/undefined before accessing
|
||||
- Test with empty and invalid data
|
||||
- Use browser console for debugging
|
||||
|
||||
**See Also**:
|
||||
- [SKILL.md](SKILL.md) - Overview and best practices
|
||||
- [DATA_ACCESS.md](DATA_ACCESS.md) - Safe data access patterns
|
||||
- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - Working examples
|
||||
@@ -0,0 +1,350 @@
|
||||
# n8n Code JavaScript
|
||||
|
||||
Expert guidance for writing JavaScript code in n8n Code nodes.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Teaches how to write effective JavaScript in n8n Code nodes, avoid common errors, and use built-in functions effectively.
|
||||
|
||||
---
|
||||
|
||||
## Activates On
|
||||
|
||||
**Trigger keywords**:
|
||||
- "javascript code node"
|
||||
- "write javascript in n8n"
|
||||
- "code node javascript"
|
||||
- "$input syntax"
|
||||
- "$json syntax"
|
||||
- "this.helpers.httpRequest" / "$helpers.httpRequest"
|
||||
- "DateTime luxon"
|
||||
- "code node error"
|
||||
- "webhook data code"
|
||||
- "return format code node"
|
||||
|
||||
**Common scenarios**:
|
||||
- Writing JavaScript code in Code nodes
|
||||
- Troubleshooting Code node errors
|
||||
- Making HTTP requests from code
|
||||
- Working with dates and times
|
||||
- Accessing webhook data
|
||||
- Choosing between All Items and Each Item mode
|
||||
|
||||
---
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
### Quick Start
|
||||
- Mode selection (All Items vs Each Item)
|
||||
- Data access patterns ($input.all(), $input.first(), $input.item)
|
||||
- Correct return format: `[{json: {...}}]`
|
||||
- Webhook data structure (.body nesting)
|
||||
- Built-in functions overview
|
||||
|
||||
### Data Access Mastery
|
||||
- $input.all() - Batch operations (most common)
|
||||
- $input.first() - Single item operations
|
||||
- $input.item - Each Item mode processing
|
||||
- $node - Reference other workflow nodes
|
||||
- **Critical gotcha**: Webhook data under `.body`
|
||||
|
||||
### Common Patterns (Production-Tested)
|
||||
1. Multi-source Data Aggregation
|
||||
2. Regex Filtering & Pattern Matching
|
||||
3. Markdown Parsing & Structured Extraction
|
||||
4. JSON Comparison & Validation
|
||||
5. CRM Data Transformation
|
||||
6. Release Information Processing
|
||||
7. Array Transformation with Context
|
||||
8. Slack Block Kit Formatting
|
||||
9. Top N Filtering & Ranking
|
||||
10. String Aggregation & Reporting
|
||||
|
||||
### Error Prevention
|
||||
Top 5 errors to avoid:
|
||||
1. **Empty code / missing return** (38% of failures)
|
||||
2. **Expression syntax confusion** (using `{{}}` in code)
|
||||
3. **Incorrect return format** (missing array wrapper or json property)
|
||||
4. **Unmatched brackets** (string escaping issues)
|
||||
5. **Missing null checks** (crashes on undefined)
|
||||
|
||||
### Built-in Functions
|
||||
- **this.helpers.httpRequest()** - Make HTTP requests (the bare `$helpers` global is undefined in the task-runner sandbox; prefer the HTTP Request node for anything beyond a trivial unauthenticated GET)
|
||||
- **DateTime (Luxon)** - Advanced date/time operations
|
||||
- **$jmespath()** - Query JSON structures
|
||||
- **$getWorkflowStaticData()** - Persistent storage
|
||||
- Standard JavaScript globals (Math, JSON, console)
|
||||
- Available Node.js modules (crypto, Buffer, URL)
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
n8n-code-javascript/
|
||||
├── SKILL.md
|
||||
│ Overview, quick start, mode selection, best practices
|
||||
│ - Mode selection guide (All Items vs Each Item)
|
||||
│ - Data access patterns overview
|
||||
│ - Return format requirements
|
||||
│ - Critical webhook gotcha
|
||||
│ - Error prevention overview
|
||||
│ - Quick reference checklist
|
||||
│
|
||||
├── DATA_ACCESS.md
|
||||
│ Complete data access patterns
|
||||
│ - $input.all() - Most common (26% usage)
|
||||
│ - $input.first() - Very common (25% usage)
|
||||
│ - $input.item - Each Item mode (19% usage)
|
||||
│ - $node - Reference other nodes
|
||||
│ - Webhook data structure (.body nesting)
|
||||
│ - Choosing the right pattern
|
||||
│ - Common mistakes to avoid
|
||||
│
|
||||
├── COMMON_PATTERNS.md
|
||||
│ 10 production-tested patterns
|
||||
│ - Pattern 1: Multi-source Aggregation
|
||||
│ - Pattern 2: Regex Filtering
|
||||
│ - Pattern 3: Markdown Parsing
|
||||
│ - Pattern 4: JSON Comparison
|
||||
│ - Pattern 5: CRM Transformation
|
||||
│ - Pattern 6: Release Processing
|
||||
│ - Pattern 7: Array Transformation
|
||||
│ - Pattern 8: Slack Block Kit
|
||||
│ - Pattern 9: Top N Filtering
|
||||
│ - Pattern 10: String Aggregation
|
||||
│ - Pattern selection guide
|
||||
│
|
||||
├── ERROR_PATTERNS.md
|
||||
│ Top 5 errors with solutions
|
||||
│ - Error #1: Empty Code / Missing Return (38%)
|
||||
│ - Error #2: Expression Syntax Confusion (8%)
|
||||
│ - Error #3: Incorrect Return Wrapper (5%)
|
||||
│ - Error #4: Unmatched Brackets (6%)
|
||||
│ - Error #5: Missing Null Checks
|
||||
│ - Error prevention checklist
|
||||
│ - Quick error reference
|
||||
│ - Debugging tips
|
||||
│
|
||||
├── BUILTIN_FUNCTIONS.md
|
||||
│ Complete built-in function reference
|
||||
│ - this.helpers.httpRequest() API reference
|
||||
│ - DateTime (Luxon) complete guide
|
||||
│ - $jmespath() JSON querying
|
||||
│ - $getWorkflowStaticData() persistent storage
|
||||
│ - Standard JavaScript globals
|
||||
│ - Available Node.js modules
|
||||
│ - What's NOT available
|
||||
│
|
||||
└── README.md (this file)
|
||||
Skill metadata and overview
|
||||
```
|
||||
|
||||
**Total**: 6 files
|
||||
|
||||
---
|
||||
|
||||
## Coverage
|
||||
|
||||
### Mode Selection
|
||||
- **Run Once for All Items** - Recommended for 95% of use cases
|
||||
- **Run Once for Each Item** - Specialized cases only
|
||||
- Decision guide and performance implications
|
||||
|
||||
### Data Access
|
||||
- Most common patterns with usage statistics
|
||||
- Webhook data structure (critical .body gotcha)
|
||||
- Safe access patterns with null checks
|
||||
- When to use which pattern
|
||||
|
||||
### Error Prevention
|
||||
- Top 5 errors covering 62%+ of all failures
|
||||
- Clear wrong vs right examples
|
||||
- Error prevention checklist
|
||||
- Debugging tips and console.log usage
|
||||
|
||||
### Production Patterns
|
||||
- 10 patterns from real workflows
|
||||
- Complete working examples
|
||||
- Use cases and key techniques
|
||||
- Pattern selection guide
|
||||
|
||||
### Built-in Functions
|
||||
- Complete this.helpers.httpRequest() reference
|
||||
- DateTime/Luxon operations (formatting, parsing, arithmetic)
|
||||
- $jmespath() for JSON queries
|
||||
- Persistent storage with $getWorkflowStaticData()
|
||||
- Standard JavaScript and Node.js modules
|
||||
|
||||
---
|
||||
|
||||
## Critical Gotchas Highlighted
|
||||
|
||||
### #1: Webhook Data Structure
|
||||
**MOST COMMON MISTAKE**: Webhook data is under `.body`
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG
|
||||
const name = $json.name;
|
||||
|
||||
// ✅ CORRECT
|
||||
const name = $json.body.name;
|
||||
```
|
||||
|
||||
### #2: Return Format
|
||||
**Prefer the canonical `[{json: {...}}]`** — unambiguous in both execution modes. A bare object auto-wraps in *Run Once for All Items* mode, so it runs too; what actually fails is returning a primitive (string/number) or `null`.
|
||||
|
||||
```javascript
|
||||
// ⚠️ Auto-wrapped in All Items mode → [{json: {result: 'success'}}]. Runs, but prefer the array form.
|
||||
return {json: {result: 'success'}};
|
||||
|
||||
// ✅ CANONICAL
|
||||
return [{json: {result: 'success'}}];
|
||||
```
|
||||
|
||||
### #3: Expression Syntax
|
||||
**Don't use `{{}}` in Code nodes**
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG
|
||||
const value = "{{ $json.field }}";
|
||||
|
||||
// ✅ CORRECT
|
||||
const value = $json.field;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### n8n Expression Syntax
|
||||
- **Distinction**: Expressions use `{{}}` in OTHER nodes
|
||||
- **Code nodes**: Use JavaScript directly (no `{{}}`)
|
||||
- **When to use each**: Code vs expressions decision guide
|
||||
|
||||
### n8n MCP Tools Expert
|
||||
- Find Code node: `search_nodes({query: "code"})`
|
||||
- Get configuration: `get_node("nodes-base.code")`
|
||||
- Validate code: `validate_node()`
|
||||
|
||||
### n8n Node Configuration
|
||||
- Mode selection (All Items vs Each Item)
|
||||
- Language selection (JavaScript vs Python)
|
||||
- Understanding property dependencies
|
||||
|
||||
### n8n Workflow Patterns
|
||||
- Code nodes in transformation step
|
||||
- Webhook → Code → API pattern
|
||||
- Error handling in workflows
|
||||
|
||||
### n8n Validation Expert
|
||||
- Validate Code node configuration
|
||||
- Handle validation errors
|
||||
- Auto-fix common issues
|
||||
|
||||
---
|
||||
|
||||
## When to Use Code Node
|
||||
|
||||
**Use Code node when:**
|
||||
- ✅ Complex transformations requiring multiple steps
|
||||
- ✅ Custom calculations or business logic
|
||||
- ✅ Recursive operations
|
||||
- ✅ API response parsing with complex structure
|
||||
- ✅ Multi-step conditionals
|
||||
- ✅ Data aggregation across items
|
||||
|
||||
**Consider other nodes when:**
|
||||
- ❌ Simple field mapping → Use **Set** node
|
||||
- ❌ Basic filtering → Use **Filter** node
|
||||
- ❌ Simple conditionals → Use **IF** or **Switch** node
|
||||
- ❌ HTTP requests only → Use **HTTP Request** node
|
||||
|
||||
**Code node excels at**: Complex logic that would require chaining many simple nodes
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Before this skill**:
|
||||
- Users confused by mode selection
|
||||
- Frequent return format errors
|
||||
- Expression syntax mistakes
|
||||
- Webhook data access failures
|
||||
- Missing null check crashes
|
||||
|
||||
**After this skill**:
|
||||
- Clear mode selection guidance
|
||||
- Understanding of return format
|
||||
- JavaScript vs expression distinction
|
||||
- Correct webhook data access
|
||||
- Safe null-handling patterns
|
||||
- Production-ready code patterns
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Essential Rules
|
||||
1. Choose "All Items" mode (recommended)
|
||||
2. Access data: `$input.all()`, `$input.first()`, `$input.item`
|
||||
3. **Return** the canonical `[{json: {...}}]` (bare objects auto-wrap in All Items mode; primitives/`null` fail)
|
||||
4. **Webhook data**: Under `.body` property
|
||||
5. **No `{{}}` syntax**: Use JavaScript directly
|
||||
|
||||
### Most Common Patterns
|
||||
- Batch processing → $input.all() + map/filter
|
||||
- Single item → $input.first()
|
||||
- Aggregation → reduce()
|
||||
- HTTP requests → this.helpers.httpRequest()
|
||||
- Date handling → DateTime (Luxon)
|
||||
|
||||
### Error Prevention
|
||||
- Always return data
|
||||
- Check for null/undefined
|
||||
- Use try-catch for risky operations
|
||||
- Test with empty input
|
||||
- Use console.log() for debugging
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **n8n Code Node Guide**: https://docs.n8n.io/code/code-node/
|
||||
- **Built-in Methods Reference**: https://docs.n8n.io/code-examples/methods-variables-reference/
|
||||
- **Luxon Documentation**: https://moment.github.io/luxon/
|
||||
|
||||
---
|
||||
|
||||
## Evaluations
|
||||
|
||||
**5 test scenarios** covering:
|
||||
1. Webhook body gotcha (most common mistake)
|
||||
2. Return format error (missing array wrapper)
|
||||
3. HTTP request with this.helpers.httpRequest()
|
||||
4. Aggregation pattern with $input.all()
|
||||
5. Expression syntax confusion (using `{{}}`)
|
||||
|
||||
Each evaluation tests skill activation, correct guidance, and reference to appropriate documentation files.
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** (2025-01-20): Initial implementation
|
||||
- SKILL.md with comprehensive overview
|
||||
- DATA_ACCESS.md covering all access patterns
|
||||
- COMMON_PATTERNS.md with 10 production patterns
|
||||
- ERROR_PATTERNS.md covering top 5 errors
|
||||
- BUILTIN_FUNCTIONS.md complete reference
|
||||
- 5 evaluation scenarios
|
||||
|
||||
---
|
||||
|
||||
## Author
|
||||
|
||||
Conceived by Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en)
|
||||
|
||||
Part of the n8n-skills collection.
|
||||
@@ -0,0 +1,407 @@
|
||||
---
|
||||
name: n8n-code-javascript
|
||||
description: Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with this.helpers / the $helpers global, working with dates using DateTime, troubleshooting Code node errors, choosing between Code node modes, or doing any custom data transformation in n8n. Always use this skill when a workflow needs a Code node — whether for data aggregation, filtering, API calls, format conversion, batch processing logic, or any custom JavaScript. Covers SplitInBatches loop patterns, cross-iteration data, pairedItem, and real-world production patterns. Also use when asked why a Code node or workflow is slow, which execution mode is faster, or how to cut per-item overhead on large datasets. EXCEPTION — for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode, a tool attached to an AI Agent), use the n8n-code-tool skill instead; it has a different runtime contract.
|
||||
---
|
||||
|
||||
# JavaScript Code Node
|
||||
|
||||
Expert guidance for writing JavaScript code in n8n Code nodes.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```javascript
|
||||
// Basic template for Code nodes
|
||||
const items = $input.all();
|
||||
|
||||
// Process data
|
||||
const processed = items.map(item => ({
|
||||
json: {
|
||||
...item.json,
|
||||
processed: true,
|
||||
timestamp: new Date().toISOString()
|
||||
}
|
||||
}));
|
||||
|
||||
return processed;
|
||||
```
|
||||
|
||||
### Essential Rules
|
||||
|
||||
1. **Choose "Run Once for All Items" mode** (recommended for most use cases)
|
||||
2. **Access data**: `$input.all()`, `$input.first()`, or `$input.item`
|
||||
3. **Return `[{json: {...}}]`** — the canonical, mode-portable form. In *Run Once for All Items* mode n8n also auto-wraps a bare `return {…}` object, so that runs too; what genuinely fails is returning a primitive (string/number) or `null`.
|
||||
4. **CRITICAL**: Webhook data is under `$json.body` (not `$json` directly)
|
||||
5. **Built-ins available**: `this.helpers.httpRequest()` (no auth — the bare `$helpers` global is **undefined** in the task-runner sandbox, so `$helpers.httpRequest()` throws `ReferenceError: $helpers is not defined`), DateTime (Luxon), $jmespath(). **Not available**: `this.helpers.httpRequestWithAuthentication` (deny-listed), $env (when N8N_BLOCK_ENV_ACCESS_IN_NODE=true), require() (unless allowlisted). For anything beyond a trivial unauthenticated GET (auth, pagination, retries), prefer the **HTTP Request node** and keep Code nodes for pure logic.
|
||||
6. **Instance-allowlisted libraries**: Self-hosted instances can allowlist modules via `N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES` and `N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES` (legacy: `NODE_FUNCTION_ALLOW_BUILTIN` / `NODE_FUNCTION_ALLOW_EXTERNAL`). If the user says their instance allows specific modules (e.g. `axios`, `lodash`, `crypto`), use them via `require()` — don't refuse. If unsure, ask or default to built-ins only.
|
||||
7. **Wrong skill?** If you're writing code for a **Custom Code Tool** attached to an AI Agent (`@n8n/n8n-nodes-langchain.toolCode`), stop — that node has a different contract (input via `query`, must return a string, no `$input`/`$helpers`). Use the **n8n-code-tool** skill.
|
||||
|
||||
---
|
||||
|
||||
## Mode Selection Guide
|
||||
|
||||
The Code node offers two execution modes. Choose based on your use case:
|
||||
|
||||
### Run Once for All Items (Recommended - Default)
|
||||
|
||||
**Use this mode for:** 95% of use cases
|
||||
|
||||
- **How it works**: Code executes **once** regardless of input count
|
||||
- **Data access**: `$input.all()` or `items` array
|
||||
- **Best for**: Aggregation, filtering, batch processing, transformations, API calls with all data
|
||||
- **Performance**: Faster for multiple items (single execution)
|
||||
|
||||
```javascript
|
||||
// Example: Calculate total from all items
|
||||
const allItems = $input.all();
|
||||
const total = allItems.reduce((sum, item) => sum + (item.json.amount || 0), 0);
|
||||
|
||||
return [{
|
||||
json: {
|
||||
total,
|
||||
count: allItems.length,
|
||||
average: total / allItems.length
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- ✅ Comparing items across the dataset
|
||||
- ✅ Calculating totals, averages, or statistics
|
||||
- ✅ Sorting or ranking items
|
||||
- ✅ Deduplication
|
||||
- ✅ Building aggregated reports
|
||||
- ✅ Combining data from multiple items
|
||||
|
||||
### Run Once for Each Item
|
||||
|
||||
**Use this mode for:** Specialized cases only
|
||||
|
||||
- **How it works**: Code executes **separately** for each input item
|
||||
- **Data access**: `$input.item` or `$item`
|
||||
- **Best for**: Item-specific logic, independent operations, per-item validation
|
||||
- **Performance**: Slower for large datasets (multiple executions)
|
||||
|
||||
```javascript
|
||||
// Example: Add processing timestamp to each item
|
||||
const item = $input.item;
|
||||
|
||||
return [{
|
||||
json: {
|
||||
...item.json,
|
||||
processed: true,
|
||||
processedAt: new Date().toISOString()
|
||||
}
|
||||
}];
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- ✅ Each item needs independent API call
|
||||
- ✅ Per-item validation with different error handling
|
||||
- ✅ Item-specific transformations based on item properties
|
||||
- ✅ When items must be processed separately for business logic
|
||||
|
||||
**Decision Shortcut:**
|
||||
- **Need to look at multiple items?** → Use "All Items" mode
|
||||
- **Each item completely independent?** → Use "Each Item" mode
|
||||
- **Not sure?** → Use "All Items" mode (you can always loop inside)
|
||||
|
||||
### Why "All Items" is faster — the per-item boundary
|
||||
|
||||
Mode choice is the single biggest performance lever in a Code node. Each *per-item* execution context costs a setup tax (measured on n8n 2.x, small records):
|
||||
|
||||
| What runs per item | Approx. cost |
|
||||
|---|---|
|
||||
| Code **All Items** (one run for the whole set) | ~0.02 ms/item |
|
||||
| Expression in any node (IF / Set / etc.) | ~0.2 ms/item |
|
||||
| Code **Each Item** (a full sandbox per item) | ~0.6 ms/item — ~25–30× All Items |
|
||||
|
||||
So `Run Once for Each Item` over 10k items is ~6 s of pure overhead vs ~0.2 s in `Run Once for All Items`. Use Each Item only when an item genuinely needs isolating (independent error handling, or a per-item API call you can't batch); otherwise loop *inside* one All Items node. Expression complexity itself is essentially free (~90% of the cost is the per-item context, not your code) and every node→node hop re-copies all items — so reduce the *number* of per-item boundaries, don't micro-optimize each one. Below a few hundred items none of this matters; reach for it on the hot path (large item counts, little I/O).
|
||||
|
||||
**See**: [DATA_ACCESS.md](DATA_ACCESS.md) → "Mode Performance" for the corollaries, hop costs, and scale check.
|
||||
|
||||
---
|
||||
|
||||
## Data Access Patterns
|
||||
|
||||
Four ways to pull data from upstream nodes. Note `$node["Name"]` and `$('Name')` need `.first().json` or `.all()` — never `.json` directly.
|
||||
|
||||
```javascript
|
||||
const allItems = $input.all(); // 1. All items — batch ops, aggregation (most common)
|
||||
const data = $input.first().json; // 2. First item — single objects, API responses
|
||||
const item = $input.item; // 3. Current item — "Each Item" mode ONLY (undefined otherwise)
|
||||
const other = $node["Webhook"].json; // 4. Named node — combine data across nodes
|
||||
```
|
||||
|
||||
Always access fields via `.json` (e.g. `item.json.name`, not `item.name`), and prefer the explicit `$input.first().json.field` over a bare `$json.field`.
|
||||
|
||||
**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for the full guide — every pattern with examples, a decision tree, and the common mistakes (mutating originals, missing length checks, `$input.item` in the wrong mode).
|
||||
|
||||
---
|
||||
|
||||
## Critical: Webhook Data Structure
|
||||
|
||||
**MOST COMMON MISTAKE**: Webhook data is nested under `.body`
|
||||
|
||||
```javascript
|
||||
// ❌ WRONG - Will return undefined
|
||||
const name = $json.name;
|
||||
const email = $json.email;
|
||||
|
||||
// ✅ CORRECT - Webhook data is under .body
|
||||
const name = $json.body.name;
|
||||
const email = $json.body.email;
|
||||
|
||||
// Or with $input
|
||||
const webhookData = $input.first().json.body;
|
||||
const name = webhookData.name;
|
||||
```
|
||||
|
||||
**Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads.
|
||||
|
||||
**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details
|
||||
|
||||
---
|
||||
|
||||
## Return Format Requirements
|
||||
|
||||
**Canonical form**: `[{json: {...}}]` — an array of objects each with a `json` property. It is unambiguous and works identically in both execution modes, so make it your default.
|
||||
|
||||
In *Run Once for All Items* mode n8n auto-normalizes looser shapes on the way out: a single bare object, or an array of bare objects, gets wrapped under `json` for you. So `return {foo: 1}` runs. What has nothing to wrap — and therefore genuinely fails at runtime with "Code doesn't return items properly" — is a primitive (string/number/boolean) or `null`/`undefined`. (n8n-mcp ≥ 2.63.0 no longer flags a bare-object return as an error; it reflects this auto-wrap behavior.)
|
||||
|
||||
### Correct Return Formats
|
||||
|
||||
```javascript
|
||||
// ✅ Single result
|
||||
return [{
|
||||
json: {
|
||||
field1: value1,
|
||||
field2: value2
|
||||
}
|
||||
}];
|
||||
|
||||
// ✅ Multiple results
|
||||
return [
|
||||
{json: {id: 1, data: 'first'}},
|
||||
{json: {id: 2, data: 'second'}}
|
||||
];
|
||||
|
||||
// ✅ Transformed array
|
||||
const transformed = $input.all()
|
||||
.filter(item => item.json.valid)
|
||||
.map(item => ({
|
||||
json: {
|
||||
id: item.json.id,
|
||||
processed: true
|
||||
}
|
||||
}));
|
||||
return transformed;
|
||||
|
||||
// ✅ Empty result (when no data to return)
|
||||
return [];
|
||||
|
||||
// ✅ Conditional return
|
||||
if (shouldProcess) {
|
||||
return [{json: processedData}];
|
||||
} else {
|
||||
return [];
|
||||
}
|
||||
```
|
||||
|
||||
### Non-Canonical Returns (auto-wrapped — prefer the canonical form)
|
||||
|
||||
```javascript
|
||||
// ⚠️ Auto-wrapped in All Items mode → [{json: {field: value}}]. Runs, but prefer the array form.
|
||||
return {
|
||||
json: {field: value}
|
||||
};
|
||||
|
||||
// ⚠️ Auto-wrapped → [{json: {field: value}}]. Runs, but add the json wrapper for clarity.
|
||||
return [{field: value}];
|
||||
|
||||
// ✅ Fine — input items already carry a json property, so returning them unchanged is a valid passthrough
|
||||
return $input.all();
|
||||
```
|
||||
|
||||
### Genuinely Broken Returns
|
||||
|
||||
```javascript
|
||||
// ❌ FAILS: primitive — n8n errors "Code doesn't return items properly"
|
||||
return "processed";
|
||||
|
||||
// ❌ FAILS: null / undefined — nothing to pass to the next node
|
||||
return null;
|
||||
```
|
||||
|
||||
**Why it matters**: The canonical `[{json: {...}}]` is unambiguous and behaves the same in both modes. n8n auto-normalizes bare objects and arrays-of-objects in All Items mode, but a primitive or `null` return has nothing to wrap and stops execution.
|
||||
|
||||
**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #3 for detailed error solutions
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns Overview
|
||||
|
||||
The most useful Code node shapes from production workflows. One quick example — sum/aggregate across all items:
|
||||
|
||||
```javascript
|
||||
const items = $input.all();
|
||||
const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0);
|
||||
return [{ json: { total, count: items.length, average: total / items.length } }];
|
||||
```
|
||||
|
||||
The full library covers 10 patterns: multi-source aggregation, regex filtering, markdown/structured-text parsing, JSON comparison, CRM/form transformation, release processing, array transformation with computed fields, Slack Block Kit formatting, top-N ranking, and string-aggregation reporting — each with variations.
|
||||
|
||||
**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) for the 10 detailed production patterns (and the Best Practices section: validate input, try-catch, filter-early, array methods over loops, console.log debugging).
|
||||
|
||||
---
|
||||
|
||||
## Error Prevention - Top Mistakes
|
||||
|
||||
The recurring Code node failures, in rough frequency order:
|
||||
|
||||
1. **Empty code / missing return** — always end with `return [...]`, and make sure *every* branch returns.
|
||||
2. **Expression syntax as code** — don't write `{{ }}` where JavaScript belongs (`return {{ $json.x }}` is a syntax error). Use `` `${$json.field}` `` or `$input.first().json.field`. `{{ }}` *inside a string literal* is fine — it's just literal text n8n won't evaluate.
|
||||
3. **Return shape** — prefer `return [{json:{...}}]`. A bare `return {…}` auto-wraps in All Items mode, but returning a primitive (string/number) or `null` is what actually fails.
|
||||
4. **Missing null checks** — use optional chaining: `item.json?.user?.email || 'fallback'`.
|
||||
5. **Webhook body nesting** — `$json.email` is undefined; use `$json.body.email`.
|
||||
6. **Auth helpers blocked** (`httpRequestWithAuthentication`) and `$env` blocked — route secrets through credentials/HTTP Request node, not the Code node sandbox.
|
||||
|
||||
**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for the comprehensive guide — each error with wrong/right code, escaping rules, the sandbox restrictions (Errors #6–#7), a prevention checklist, and a quick error-message lookup table.
|
||||
|
||||
---
|
||||
|
||||
## Built-in Functions & Helpers
|
||||
|
||||
```javascript
|
||||
// HTTP requests (no auth — see sandbox note below)
|
||||
const res = await this.helpers.httpRequest({ method: 'GET', url: 'https://api.example.com/data' });
|
||||
|
||||
// DateTime (Luxon): now, formatting, arithmetic
|
||||
const now = DateTime.now();
|
||||
const formatted = now.toFormat('yyyy-MM-dd');
|
||||
const tomorrow = now.plus({ days: 1 });
|
||||
|
||||
// $jmespath() — query JSON structures
|
||||
const adults = $jmespath($input.first().json, 'users[?age >= `18`]');
|
||||
|
||||
// $getWorkflowStaticData() — data that persists across executions
|
||||
```
|
||||
|
||||
**Sandbox (since n8n v2.0, JsTaskRunnerSandbox):** the accessor is `this.helpers.httpRequest()` — the bare `$helpers` global is **undefined** here (`$helpers.httpRequest()` throws `ReferenceError`). Inside a nested async function where `this` is lost, call it as `await fn.call(this, ...)`. `this.helpers.httpRequestWithAuthentication` and `this.helpers.requestWithAuthenticationPaginated` are deny-listed (→ `UnsupportedFunctionError`); for authenticated calls use an **HTTP Request node** with the credential (preferred), a sub-workflow, or a manual `Authorization: Bearer ${token}` header on `this.helpers.httpRequest()` only when the token already flows through the workflow as data. `$env` is blocked when `N8N_BLOCK_ENV_ACCESS_IN_NODE=true`; `require()` works only for allowlisted modules. `Buffer`, `URL`, and standard JS globals (Math, JSON, Object, Array) always work.
|
||||
|
||||
**See**: [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) for the complete reference — full httpRequest options, all DateTime/Luxon operations, JMESPath patterns, static-data use cases, and the sandbox-restriction details.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Validate input first** — guard for empty arrays / missing `.json` before processing.
|
||||
- **Try-catch risky work** (HTTP calls) and return an error object instead of crashing.
|
||||
- **Prefer array methods** (`filter`/`map`/`reduce`) over manual loops.
|
||||
- **Filter early, transform late** — shrink the dataset before expensive work.
|
||||
- **Descriptive names** and `console.log()` for debugging (output goes to the browser console).
|
||||
|
||||
**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) → "Best Practices" for code examples of each.
|
||||
|
||||
---
|
||||
|
||||
## Production Gotchas
|
||||
|
||||
Hard-won lessons from real deployments — summarized here, with code in [DATA_ACCESS.md](DATA_ACCESS.md) → "Production Gotchas":
|
||||
|
||||
- **SplitInBatches outputs are counterintuitive**: `main[0]` = **done** (fires once, after all batches), `main[1]` = **each batch** (the loop body). Add a **Limit 1** node after the done output as a safety.
|
||||
- **Iteration count is the cost**: each loop iteration re-runs the whole body through the engine (~0.8 ms overhead each). `batchSize: 1` is the loop equivalent of *Each Item* — use the largest batch your real constraint (rate limit, page size, memory) allows, or don't loop at all.
|
||||
- **Cross-iteration accumulation (CRITICAL)**: after the loop, `$('Node Inside Loop').all()` returns ONLY the last iteration's items. Accumulate via `$getWorkflowStaticData('global')` (reset before, push inside, read after).
|
||||
- **pairedItem**: when emitting items that don't map 1:1 to input, set `pairedItem: { item: i }` or downstream Set nodes fail with `paired_item_no_info`.
|
||||
- **Node reference syntax**: `$('Node').first().json` or `$('Node').all()` — never `.json` directly on the reference.
|
||||
- **Float precision**: compare currency at the cent level — `Math.round(a*100) !== Math.round(b*100)` — to avoid false positives from float noise.
|
||||
|
||||
---
|
||||
|
||||
## When to Use Code Node
|
||||
|
||||
> **Before reaching for a Code node, walk the transform gatekeeper** in the n8n Expression Syntax skill: expression → arrow-function IIFE inside an Edit Fields field → Code node, in that order. The first two paths cover most "transform this data" tasks at ~1–10ms each, versus the Code node's sandboxed ~500–1000ms — a ~100x gap on pure single-item shaping, with no functional difference. The Code node earns its place only for whole-dataset aggregation (`$input.all()`), allowlisted libraries, or async work. And before writing code for crypto (HMAC, hashing, signing) or XML/SOAP/RSS parsing, check for a **native node** — n8n has a Crypto node (`nodes-base.crypto`) and an XML node (`nodes-base.xml`) that cover those without any JavaScript. Dropping into Code for something a native node already does is one of the most common false positives.
|
||||
|
||||
Use Code node when:
|
||||
- ✅ Complex transformations requiring multiple steps
|
||||
- ✅ Custom calculations or business logic
|
||||
- ✅ Recursive operations
|
||||
- ✅ API response parsing with complex structure
|
||||
- ✅ Multi-step conditionals
|
||||
- ✅ Data aggregation across items
|
||||
|
||||
Consider other nodes when:
|
||||
- ❌ Simple field mapping → Use **Set** node
|
||||
- ❌ Basic filtering → Use **Filter** node
|
||||
- ❌ Simple conditionals → Use **IF** or **Switch** node
|
||||
- ❌ HTTP requests only → Use **HTTP Request** node
|
||||
|
||||
**Code node excels at**: Complex logic that would require chaining many simple nodes
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### Works With:
|
||||
|
||||
**n8n Expression Syntax**:
|
||||
- Expressions use `{{ }}` syntax in other nodes
|
||||
- Code nodes use JavaScript directly (no `{{ }}`)
|
||||
- When to use expressions vs code
|
||||
|
||||
**n8n MCP Tools Expert**:
|
||||
- How to find Code node: `search_nodes({query: "code"})`
|
||||
- Get configuration help: `get_node({nodeType: "nodes-base.code"})`
|
||||
- Validate code: `validate_node({nodeType: "nodes-base.code", config: {...}})`
|
||||
|
||||
**n8n Node Configuration**:
|
||||
- Mode selection (All Items vs Each Item)
|
||||
- Language selection (JavaScript vs Python)
|
||||
- Understanding property dependencies
|
||||
|
||||
**n8n Workflow Patterns**:
|
||||
- Code nodes in transformation step
|
||||
- Webhook → Code → API pattern
|
||||
- Error handling in workflows
|
||||
|
||||
**n8n Validation Expert**:
|
||||
- Validate Code node configuration
|
||||
- Handle validation errors
|
||||
- Auto-fix common issues
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Checklist
|
||||
|
||||
Before deploying Code nodes, verify:
|
||||
|
||||
- [ ] **Code is not empty** - Must have meaningful logic
|
||||
- [ ] **Return statement exists** - Returns items, not a primitive/`null`
|
||||
- [ ] **Canonical return format** - Each item: `{json: {...}}` (bare objects auto-wrap, but be explicit)
|
||||
- [ ] **Data access correct** - Using `$input.all()`, `$input.first()`, or `$input.item`
|
||||
- [ ] **No `{{ }}` written as code** - Use JavaScript template literals: `` `${value}` ``
|
||||
- [ ] **Error handling** - Guard clauses for null/undefined inputs
|
||||
- [ ] **Webhook data** - Access via `.body` if from webhook
|
||||
- [ ] **Mode selection** - "All Items" for most cases
|
||||
- [ ] **Performance** - Prefer map/filter over manual loops
|
||||
- [ ] **Output consistent** - All code paths return same structure
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Related Files
|
||||
- [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive data access patterns
|
||||
- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 production-tested patterns
|
||||
- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions
|
||||
- [BUILTIN_FUNCTIONS.md](BUILTIN_FUNCTIONS.md) - Complete built-in reference
|
||||
|
||||
### n8n Documentation
|
||||
- Code Node Guide: https://docs.n8n.io/code/code-node/
|
||||
- Built-in Methods: https://docs.n8n.io/code-examples/methods-variables-reference/
|
||||
- Luxon Documentation: https://moment.github.io/luxon/
|
||||
|
||||
---
|
||||
|
||||
**Ready to write JavaScript in n8n Code nodes!** Start with simple transformations, use the error patterns guide to avoid common mistakes, and reference the pattern library for production-ready examples.
|
||||
Reference in New Issue
Block a user