How to use Claude Code to write and debug n8n function nodes

The function node in n8n lets you write JavaScript to transform data, run custom logic, or handle anything the built-in nodes cannot do. It is the escape hatch for everything else.

It is also where most n8n beginners hit a wall. The error messages are cryptic. The data structure is not always obvious. And the debugging experience — running the workflow, reading the output panel, editing the code, running again — is slower than a proper development environment.

Claude Code removes most of this friction. But only if you know how to give it the right context. Without the actual data structure the node is working with, Claude will guess — and it will often guess wrong.

The most common mistake when asking Claude Code to write a function node is describing what the data looks like rather than showing it. Claude needs the actual JSON structure to write code that correctly references the right fields.

Before you ask Claude anything, run your workflow up to the node before the function node. Click on that previous node and open the Output panel. This shows you the exact JSON structure that the function node will receive. Copy the full output.

Paste that JSON into Claude Code. Tell it the current data structure is the input, describe what you want the output to look like, and ask it to write the function node code. It will produce code that correctly references the actual field names and handles the actual data shape rather than an imagined version of it.

This one change — showing the real data instead of describing it — eliminates most of the back-and-forth in function node debugging.

The prompt structure that works consistently: paste the input data, describe the transformation you want, specify what the output should look like, and ask for function node code compatible with n8n.

Explicitly telling Claude you are writing for n8n matters. n8n function nodes have a specific structure: they receive an items array, you iterate over it, and you return a modified items array. Claude knows this pattern but benefits from the explicit reminder.

An example prompt structure: "I am writing an n8n function node. Here is the input data structure: [paste JSON]. I need the function node to [describe transformation]. The output should be [describe output format]. Write the function node code."

If you want Claude to add error handling, ask for it explicitly. By default it will write the happy path. For production workflows, ask it to wrap the main logic in a try-catch and return the original item with an error field set if something fails. This prevents one bad row from crashing the entire workflow.

When a function node fails, you have three pieces of information: the input data, the current code, and the error message. Give Claude all three and tell it what you expected to happen versus what actually happened.

Do not just paste the error message. Paste the full context. Claude's ability to diagnose the problem correctly is proportional to how much of the relevant context you give it.

The most common function node errors follow predictable patterns. Cannot read property X of undefined usually means the code is trying to access a field that does not exist on some rows — the fix is adding a null check or using optional chaining. TypeError means the code is calling a method on a value of the wrong type, usually because a number came through as a string or an expected array is actually an object.

For both of these, Claude will fix the immediate error. Ask it also to scan the rest of the code for the same pattern and fix any other instances. This prevents the same class of error from appearing on a different row later.

n8n's hosted version and some self-hosted versions run older Node.js environments. Modern JavaScript syntax that works fine locally may error in production.

If you paste function node code into n8n and it fails with a syntax error you do not recognise, tell Claude Code: "This code needs to run in n8n on a Node.js 14 environment. Rewrite it to be compatible." Claude will replace optional chaining, nullish coalescing, and other newer syntax with equivalent code that runs on older environments.

The other common compatibility issue is with async operations. n8n function nodes do not natively support async/await in all versions. If you need to make an API call or do anything asynchronous inside a function node, use the HTTP Request node instead and chain it. Trying to handle async operations inside function nodes creates subtle bugs that are hard to diagnose.

The function node is powerful for synchronous data transformation. For anything involving external requests or async logic, the built-in nodes are the better path.