n8n 3.0 Breaking Changes: What Actually Breaks

Here's the official 3.0 breaking-changes page compressed into the things that can actually stop a running instance:

• Docker only. Self-hosted n8n no longer supports installs run with npm or npx. This is the one that ends your evening.
• AI Agent node v1 removed. Along with the SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent and ReAct Agent modes.
• Legacy nodes removed. Function, Function Item and Item Lists are gone.
• $getPairedItem removed. Use the pairedItem property or $("node-name").item instead.
• Execute Workflow changed. The older behavior is dropped.
• Compression limits cut ~8x. Max decompressed size falls from 2 GiB to 256 MiB; max zip entries from 5,000 to 1,000.
• Retired features. Chat Hub, workflow import from URL in the editor, and a handful of non-functional nodes.
• Security tightening. Stricter handling of risky resource names, safer credential behavior, and key rotation on by default.

Read that list once and the shape is obvious. Seven of the eight items are node-level chores you can fix in an afternoon. One is an infrastructure migration.

The changelog puts it bluntly: npm installs stop working with n8n 3.0 in October. If you started your instance with a global n8n binary, a systemd unit calling npm start, or — and I've seen this in production more than once — a npx n8n inside a screen session, that host does not get to upgrade. It gets rebuilt.

Why this bites harder than it reads: an npm install almost always means SQLite sitting in ~/.n8n, and an encryption key sitting next to it in config. Move the container without moving that key and every credential in your instance decrypts to garbage. You won't get a clean error either — you get nodes failing auth one by one while the workflow list looks perfectly healthy.

Do the Docker move now, on a normal Tuesday, while you're still on 2.x. Mount ~/.n8n as a volume, set N8N_ENCRYPTION_KEY explicitly from the old file, bring the container up on the same version you were already running, and confirm credentials still work before you change anything else. Two variables at a time is how you end up bisecting a broken instance at midnight.

If you're going to be moving the deployment anyway, it's a decent moment to re-run the hosting decision — I wrote up the tradeoffs in n8n Cloud vs self-hosted for 2026. And if you're already containerized but running a single process, this is also the natural time to look at queue mode, since you're editing the compose file regardless.

Rather than guess, I pulled every workflow off the client instance I run and counted. 182 workflows. Here's what the 3.0 removal list actually hit:

Sixty-two AI Agent nodes across the instance. Twelve still on the old typeVersion — six at 1.7, six at 1.9. And of those twelve, eleven were already running as the default Tools Agent, because the agent type setting has been deprecated since n8n 1.82.0 and everything defaulted there on its own. Exactly one node, in a workflow called “Blog Creator,” still had agent: conversationalAgent set explicitly.

So the honest scoreboard on a fairly busy instance is: one workflow needs thinking about, eleven need a click. The legacy-node removals — the ones that read scariest in the changelog because they kill named nodes — hit nothing at all, because anything built in the last two years uses the Code node anyway.

That's the useful part of doing the audit instead of reading the list and bracing. If your instance is younger than about 2024, most of this release is a non-event and you can spend the whole budget on the Docker migration, which is where the actual risk lives.

Twenty lines, no dependencies, run it per environment. It reads the public REST API, so it works the same on 2.x whether you're on Docker or not:

import json, urllib.request

REMOVED = {"n8n-nodes-base.function", "n8n-nodes-base.functionItem",
           "n8n-nodes-base.itemLists"}
DEAD_MODES = {"conversationalAgent", "sqlAgent", "openAiFunctionsAgent",
              "planAndExecuteAgent", "reActAgent"}

req = urllib.request.Request(
    "https://YOUR-N8N/api/v1/workflows?limit=250",
    headers={"X-N8N-API-KEY": "YOUR_KEY"})
wfs = json.load(urllib.request.urlopen(req))["data"]

for w in wfs:
    for n in w.get("nodes") or []:
        t, tv = n.get("type"), n.get("typeVersion")
        mode = (n.get("parameters") or {}).get("agent")
        if t in REMOVED:
            print("REMOVED NODE", w["name"], t)
        if t == "@n8n/n8n-nodes-langchain.agent" and tv and tv < 2:
            tag = "REWRITE" if mode in DEAD_MODES else "bump"
            print(tag, w["name"], "typeVersion", tv, mode or "toolsAgent")
    if "$getPairedItem" in json.dumps(w):
        print("PAIRED ITEM", w["name"])

The typeVersion check is the one people get wrong. The node type string doesn't change between v1 and v2 of the AI Agent — only the version number does — so searching for the node name in the editor tells you nothing. And read parameters.agent before you panic: an absent value means it was already a Tools Agent, and a Tools Agent workflow keeps behaving the same after you update the node.

Run it against staging and production separately. My local instance came back with 11 workflows and zero findings; the client instance is where all twelve hits were. That difference is the entire argument for auditing per environment instead of extrapolating from the box on your desk.

Buried under the security section: N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES drops from 2 GiB to 256 MiB, and N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES from 5,000 to 1,000. These are zip-bomb defenses and the new numbers are the right call.

They're also the kind of change that breaks exactly one workflow you forgot exists — the nightly job that unpacks a vendor export. It won't fail at upgrade time. It'll fail at 3am on the first night the archive crosses the line, and if you've got an error workflow that never actually fires, you'll find out from the client. Both ceilings are still env vars, so you can raise them deliberately — just raise them because you decided to, not because a job started failing.

Same category: Chat Hub is retired, and so is importing a workflow from a URL inside the editor. If any part of your deploy process depends on that URL import, move it to the API or to a proper git-backed workflow before October.

In order, because the order matters:

1. Move to Docker first, on your current version. Same n8n version, same database, encryption key carried over explicitly. Verify credentials before you celebrate. This is the only step with a real blast radius.
2. Run the audit script per environment. Ten minutes. You now have a finite list of workflow names instead of a feeling.
3. Bump the easy Agent nodes. Anything on typeVersion 1.x already defaulting to Tools Agent: update, run once, move on.
4. Rewrite the removed modes. SQL Agent becomes a Tools Agent plus a Postgres or MySQL tool sub-node. The others become Tools Agents with the right tools attached. If the rewrite is turning into a mess, that's usually a sign the capability wants to be a sub-workflow rather than a tool.
5. Upgrade to 3.0 on staging, then production. Not the week it ships. Give the .1 a moment.

One thing worth saying plainly: n8n is shipping stable releases most weeks and is already deep in the 2.3x range. A major version that removes five-year-old nodes and forces a supported deployment model is a healthy signal, not a hostile one. The npm requirement in particular kills an entire class of “it works on my VPS” support ticket. It's just going to be a rough month for anyone who never wrote down how their instance was installed.