Everything so far, and the jobs it still cannot reach

By now the shape of a workflow should be familiar. Eight cases out of ten come down to a core node plus a SaaS integration node: pull data, filter it, send a message, write it to a database. The Edit Fields (Set) node reshapes what comes through, expressions fill values in dynamically, and Merge and the splitting nodes put the pieces back together.

Then there is the ten percent. These are the jobs where the ready-made nodes run out, and they are more specific than “something complicated”:

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

flowchart LR
  A["Upstream node
hands over an array of items"] --> B["Code node
your JavaScript runs"]
  B --> C["A new array of items
comes out"]
  C --> D["Next node
Slack, Sheets, HTTP Request"]
  E["Ready-made nodes already cover
about eight cases in ten"] -.-> B

If Set, IF or Switch can do it, do not open a Code node

The Code node looking capable is not a reason to reach for it. Code is JavaScript, and whoever maintains the workflow later — often you, months on — has to read that code and know JavaScript as well. That bar is a great deal higher than a visual node, so the question to ask before opening one is always whether the built-in nodes could have done the job.

Here is that question worked through for the seven things people most often reach for Code to do.

flowchart TD
  A["You need to select,
reshape or summarize data"] --> B{"Could three Set nodes
do this?"}
  B -->|"yes"| C["Set, IF, Switch,
Filter or Aggregate"]
  B -->|"no"| D{"Does it need a loop, a sort,
or three levels of nesting?"}
  D -->|"no"| E["Try the visual nodes first.
Come back if they run out"]
  D -->|"yes"| F["Open a Code node"]
  C --> G["Readable by the next person
without knowing JavaScript"]

Two languages in the dropdown, and one of them to pick

Open a Code node and there is a Language option toward the top right with two choices: JavaScript and Python. In practice, pick JavaScript around 99% of the time. The reasons are worth knowing, because they are not about which language is nicer.

“I am better at Python” on its own is not a good reason. The community and the examples are all on the JavaScript side, which means every answer you find when you get stuck will need translating first.

Every remaining example on this page is JavaScript. If you do end up in Python, the syntax differs in two ways worth writing down: 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, which is exactly the line that breaks when somebody copies an old forum answer. When you need the detail, the official page is docs.n8n.io/build/code-in-n8n/using-the-code-node/.

All items at once, or one item at a time

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 rather than throwing a tidy error.

flowchart TD
  A["Items arrive at the Code node"] --> B{"Which mode is selected?"}
  B -->|"Run Once for All Items"| C["Your code runs once.
Read every item at once"]
  C --> D["Return an array of items"]
  B -->|"Run Once for Each Item"| E["Your code runs once per item.
Read the current item only"]
  E --> F["Return one single item"]
  D --> G["Downstream node"]
  F --> G

Every example below assumes All Items mode unless it says otherwise.

Filter, map, aggregate, call an API

These four cover the overwhelming majority of Code nodes anyone writes. Read them as templates: copy one, change the field names and the conditions, and leave the structure alone.

flowchart LR
  A1["20 items in"] --> B1["filter
a condition removes some"] --> C1["6 items out"]
  A2["20 items in"] --> B2["map
every item transformed"] --> C2["20 items out"]
  A3["20 items in"] --> B3["aggregate
reduced to one total"] --> C3["1 item out"]
  A4["1 item in"] --> B4["call an API
and wait for the answer"] --> C4["1 item with the response"]

Pattern 1 · filter

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

In plain words, reading it left to right:

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

Swap amount > 1000 for whatever you need — item.json.status === 'paid' and item.json.tags.includes('VIP') both work the same way. Chain several conditions with && for “and” and || for “or”:

Pattern 2 · map, to transform each item

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

• .map(item => ({...})) runs that function on every item and returns a new item for each one.
• { json: {...} } is 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: and age: are the fields you want in the output. Write whichever fields you want to keep.

Notice what that example throws away: anything not listed is gone. If you only want to add a field to the original item rather than rebuild it, use the spread syntax to keep every original field and then add the new ones:

The three dots in ...item.json are JavaScript's spread operator — read it as “flatten every field of item.json in right here”. Writing it this way saves you listing every field by hand, and it survives the upstream node gaining a new field next month.

Pattern 3 · aggregate

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

• .reduce((sum, item) => sum + item.json.amount, 0) is JavaScript's reduce, for adding an array up as it goes. sum starts at 0, which is the second argument; each pass adds item.json.amount to it; 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 are returning only one item. Forget the outer [] and it blows up.

To group by something rather than totalling everything — a total per customer, say — pair reduce with an object accumulator:

What that does is sort every order into piles by customer, total each pile, and return one item per customer. It is the most common example of “Set cannot do it, but one block of Code can” — and it is exactly the two-line job that turns into six nodes if you insist on staying visual.

Pattern 4 · call an external API from inside the Code node

This one is rare, and it should stay 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 proper interface for headers, authentication and retry, none of which you get for free in code. If you really do need the call inside Code:

this.helpers.httpRequest(...) is a helper n8n builds in — the HTTP Request node, written out in code. Use it when one stretch of logic has to call several 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 instead and keep the credential where the credential belongs.

The eleven variables n8n hands you, and the few you will actually use

The Code node comes with a pile of helpers n8n injects for you — the variables that start with $. Ninety percent of the time you only ever touch the first few in this list, but it is worth reading the whole thing once so you know what exists when you need it.

Note the quoting style in $('Node Name'): single quotes around the node's name, exactly as the node is labeled on the canvas. Rename a node on the canvas and every $('Node Name') that refers to it has to be updated by hand — nothing rewrites those for you.

The full list, including the more advanced entries, is in the official docs at docs.n8n.io/code/builtin/overview/. That page also covers $jmespath() for JMESPath queries, $max() and $min(), and DateTime for calling the Luxon constructor directly.

Four steps, six error messages, and the mistake everyone makes

The Code node throws more errors than any other node type, for the obvious reason that you are writing code in it. The good news is that n8n's error messages are usually clear enough to act on. Work through these four steps in order rather than rereading the code hopefully.

1. Step 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. SyntaxError at line 3 means go to line 3 and look for an unmatched quote or an unclosed bracket. Do not start by rewriting the logic; start at the line the message named.

2. Step 2

   Check that node's log on the Executions page

   In the left sidebar go to 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. Step 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 of all: a bare return [{ name: 'Elmo' }] makes n8n read every item as empty. The correct form is return [{ json: { name: 'Elmo' } }].

4. Step 4

   Print nested objects properly

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

flowchart TD
  A["The Code node did not do
what you expected"] --> B{"Did the node turn red?"}
  B -->|"yes"| C["Read the message under the node.
It usually names a line number"]
  C --> D["Go to that line: unmatched quote,
unclosed bracket, wrong arrow"]
  B -->|"no"| E{"What did the next node receive?"}
  E -->|"nothing at all"| F["Check the return statement,
then check the json wrapper"]
  E -->|"data, but wrong"| G["Open Executions, pick the run,
read that node's Logs tab"]
  G --> H["Print nested objects as readable JSON
before you log them"]

The six messages you will actually see

Questions that come up every time

Where to go from here