Code node: a few lines of JavaScript inside a workflow

Why the Code node

After the first 19 chapters you will have noticed that eight cases out of ten are handled by a core node plus a SaaS integration node: pull data, filter it, send a message, write to a database. The Set node reshapes it, expressions fill values in dynamically, and Merge/Split put it back together.

But there is always that 10% the ready-made nodes cannot do:

• Orders pulled out of a CRM that have to be regrouped along two dimensions, customer tier × product category — the Set node cannot do it, because that takes a loop.
• An API response buried three levels deep in { result: { data: { items: [...] } } } when all you want is the items array — one expression can do it, but add a little more logic and it turns into a mess.
• Shopify hands you 20 orders and you have to work out what percentage of total revenue the three largest ones account for — that takes sort, slice and reduce together.
• Turning 100 items into the JSON structure Slack Block Kit expects — piles of nested { type, elements: [...] }, which would drive you mad in the Set node.

That is where the Code node comes in. It gives you a blank JavaScript editor: items go in, you write a few lines of code, items come out. You do not need to know how to build applications — for most situations, copying one of the four patterns below and changing the parameters is enough.

Ask first: if Set can do it, do not use Code

The Code node looking cool is not a reason to overuse it. If Set / IF / Switch can solve it, do not open a Code node — because the Code node is JavaScript, and whoever maintains it later (or future you) has to read the code and know JS as well. That bar is a lot higher than a visual node.

The Code node gives you two languages

Open a Code node and the Language option in the top right has two choices: JavaScript and Python. In practice, pick JavaScript 99% of the time. Here is why.

Every remaining example in this chapter is JavaScript. The Python syntax differs like this: variables start with an underscore (_input, _json), and the native Python runner only takes bracket access (_input.item['json']['amount']) — the _input.item.json.amount dot syntax that old Pyodide allowed no longer works. When you need it, see the official docs at docs.n8n.io/build/code-in-n8n/using-the-code-node/.

Two run modes: all items at once vs one item at a time

Open a Code node and at the top of the Parameters panel on the right (next to the Language option) there is a Mode dropdown — the official docs word it "Choose a mode". The two options behave very differently, and picking the wrong one duplicates or drops data.

Pattern 1: filter

Pick the items that match a condition out of a pile of them. All Items mode.

// Keep only orders over 1000
return $input.all().filter(item => item.json.amount > 1000);

In plain words:

• $input.all(): gives you every item that came in (an array).
• .filter(item => ...): a built-in JavaScript array method. It runs that test on every item and keeps only the ones where it is true.
• item.json.amount > 1000: the test itself. Change this to your own condition and you are done.
• return ...: hands the result to the downstream node.

Copy this, swap amount > 1000 for the condition you want (item.json.status === 'paid' and item.json.tags.includes('VIP') both work), and that is it. Chain several conditions with && (and) and || (or):

// Amount over 1000 and tier is gold
return $input.all().filter(item =>
  item.json.amount > 1000 && item.json.tier === 'gold'
);

Pattern 2: map (transform each item)

Transform every item: add a field, change a field, calculate a new value. All Items mode.

// Combine firstName and lastName into fullName; keep only fullName and age
return $input.all().map(item => ({
  json: {
    fullName: item.json.firstName + ' ' + item.json.lastName,
    age: item.json.age
  }
}));

In plain words:

• .map(item => ({...})): runs that function on every item and returns a new item.
• { json: {...} }: the format n8n requires for an item — every item has to be wrapped in a json layer. This one is easy to forget, and forgetting it throws Items to return were not valid.
• fullName: ..., age: ...: the fields you want in the output. Write whichever fields you want to add.

If you only want to add a field to the original item rather than rebuild it, use the spread syntax ...item.json to keep every original field and then add the new ones:

// Keep every original field, then add taxAmount and total
return $input.all().map(item => ({
  json: {
    ...item.json,                      // spread the original fields
    taxAmount: item.json.amount * 0.05,
    total: item.json.amount * 1.05
  }
}));

The three dots in ...item.json are JavaScript's spread — "flatten every field of item.json in right here". Writing it this way saves you listing every field by hand.

Pattern 3: aggregate

Shrink a pile of items down to one total. All Items mode.

// Sum every order amount, then work out revenue and item count
const total = $input.all().reduce((sum, item) => sum + item.json.amount, 0);
const count = $input.all().length;

return [{
  json: {
    total: total,
    count: count,
    average: total / count
  }
}];

In plain words:

• .reduce((sum, item) => sum + item.json.amount, 0): JavaScript's reduce, for adding an array up as it goes. sum starts at 0 (the second argument), each pass adds item.json.amount to it, and the total comes back at the end.
• $input.all().length: the length of the array is the item count.
• return [{ json: {...} }]: note that it still has to be wrapped in an array, even when you return only one item — [{ json: {} }]. Forget the outer [] and it blows up.

To group by something (totalling per customer, say), pair reduce with an object accumulator:

// Total the amounts per customer name
const groups = $input.all().reduce((acc, item) => {
  const key = item.json.customer;
  acc[key] = (acc[key] || 0) + item.json.amount;
  return acc;
}, {});

// turn it back into an items array and return it
return Object.entries(groups).map(([customer, total]) => ({
  json: { customer, total }
}));

What this does: sort every order into piles by customer, total each pile, and return one item per customer. This is the most common example of "Set cannot do it, but one block of Code can".

Pattern 4: call an external API from the Code node (rare)

Inside a Code node you can await a call to an external API directly, but the HTTP Request node is usually easier to maintain — it has a UI for headers, auth and retry. If you really do need the call inside Code:

// Call an external API and return the response as one item
const response = await this.helpers.httpRequest({
  method: 'GET',
  url: 'https://api.example.com/x',
  headers: { 'Accept': 'application/json' }
});

return [{ json: response }];

this.helpers.httpRequest(...) is a helper n8n builds in — the HTTP Request node, written in code. When to use it: when one stretch of logic has to call N APIs in a row, or when a field on an item decides whether to call at all. For a plain single API call, drop in an HTTP Request node.

Common helper APIs at a glance

The Code node comes with a pile of helpers n8n injects for you (the variables starting with $). 90% of the time you only ever use the few below.

For the full list see the official docs at docs.n8n.io/code/builtin/overview/, which also covers the more advanced ones: $jmespath() (JMESPath queries), $max() / $min(), and DateTime (calling the Luxon constructor directly).

What to do when the Code node fails

The Code node throws more errors than any other node type, because you are writing code. The good news is that n8n's error messages are usually clear enough — work through the 4 steps below.

1. Read the red error message under the node panel

   When a Code node fails, the node itself turns red and an error message appears below it, usually including a line number. For example SyntaxError at line 3 — jump straight to line 3 and check for an unmatched quote or an unclosed bracket.

2. Check that node's log on the Executions page

   Left sidebar Executions → click the failed run → click the Code node → switch to the Logs tab at the top. Every console.log(x) you wrote shows up here. Log as much as you like while you are still building; nobody will hold it against you.

3. Check the output is in the right format

   The Code node ran fine but the downstream node gets nothing? Check whether the output is in the [{ json: {...} }] shape — an array on the outside, every item wrapped in json. Forgetting the json wrapper is the most common mistake: a bare return [{ name: 'Elmo' }] makes n8n read every item as empty. Correct: return [{ json: { name: 'Elmo' } }].

4. Print nested objects with console.log(JSON.stringify(x, null, 2))

   A plain console.log(item) sometimes prints only [object Object] and shows you nothing. Use JSON.stringify(item, null, 2) to turn the object into readable JSON before printing, and even several layers of nesting are clear at a glance.

Common pitfalls

1. SyntaxError: Unexpected token or Unexpected identifier

   A JavaScript syntax error, usually unmatched quotes, an unclosed bracket, or a stray semicolon. The error message gives you the line number; go and look at that line and the ones around it. Common cases: mixing Chinese quotation marks “” with English '' (the first pair are not valid JS quotes); one half of a curly brace {} missing; => typed as ->.

2. Cannot read properties of undefined (reading 'xxx')

   The field you are reaching for has nothing in its parent. For example item.json.customer.email, when the customer field does not exist. Fixes: (a) use optional chaining, item.json.customer?.email; (b) add an if test, if (!item.json.customer) return null;; (c) fix the upstream node first and confirm it really returns customer.

3. The output is empty and the downstream node gets nothing

   Three common causes: (a) you forgot the return — a function with no return gives back undefined; (b) you forgot the { json: {} } wrapper — n8n does not recognize your output; (c) the filter condition is too strict — no item matches, so the result is an empty array. That is normal, but check whether you tightened the condition too far.

4. Code runs very slowly (>30-second timeout)

   Usually a large array (>10,000 items) running .map / .filter. The fix: put a Split In Batches node upstream and work in batches, feeding 500-1000 items into the Code node at a time. Or check the code for a nested loop (a .map with a .filter inside it) — that is O(n²), and it blows up as soon as the data grows.

5. Items to return were not valid

   What you returned is not in n8n's item format. The correct shape: [{ json: {...} }] — an array on the outside, and every element an object with a json key. Wrong: return { name: 'Elmo' } (not an array), return [{ name: 'Elmo' }] (no json wrapper). Each Item mode returns a single { json: {} }; All Items mode returns an array.

6. ReferenceError: fetch is not defined or require is not defined

   The Community edition sandbox does not enable fetch or require. Call APIs with await this.helpers.httpRequest({...}) instead; to pull in an npm package, self-hosting is the only route — set the environment variable NODE_FUNCTION_ALLOW_EXTERNAL=lodash to open it up (not possible on Cloud).

FAQ