Preparing for n8n 3.0: Docker-Only, Removed Nodes, and a 90-Day Timeline

This post is adapted from Chapter 34 of the free book The Ultimate Guide to Deploying n8n Community Edition (2nd edition, September 2026, covering n8n 2.38). Grab the full PDF or EPUB, download the free self-hosting starter excerpt, or join the House of Loops community to swap workflows with other self-hosters.

Overview

n8n 3.0 is scheduled for October 2026. n8n's own breaking-changes notice describes it as a security- and cleanup-focused major release: tighter defaults, a Docker-only deployment model, and the removal of nodes and helpers that newer patterns replaced years ago. For most recently built workflows, none of this touches you. For anyone still running n8n with npm or npx n8n, or with workflows built on the old Function node, Item Lists node, or version 1 of the AI Agent node, it does.

This guide covers what n8n has confirmed will change, what to do about it now, and how to find out today whether your workflows are affected. It does not guess at anything n8n hasn't published. n8n's breaking-changes page says outright: "n8n will update this page with full details, migration guides, and links as n8n 3.0 approaches its release." The exact shape of the tighter security defaults, and the full list of "non-functional nodes" being retired, are still vague in the source document as of this writing. Where that's true, this guide says so instead of inventing detail.

You will:

1. Understand the headline change: Docker-based self-hosting only.
2. Get a migration path off npm, npx, or PM2, if you're still on one of them.
3. See every removed node and helper mapped to its replacement.
4. Understand what changes for the Execute Workflow node and the AI Agent node.
5. Know what's tightening in security defaults, including the Compression node.
6. Learn what's being retired outright.
7. Run a one-line scan across your workflow exports to find out if this affects you today.
8. Get a 90-day timeline to work from before release.

Prerequisites

• An n8n instance on the 2.x line (this book's reference stack runs n8nio/n8n:2.38.1 — see our Docker Compose guide).
• Shell access to your workflow exports, and jq installed for the scanning script in Section 9.
• If you're on npm or npx n8n: the full guide covers migrating from legacy Node.js and PM2 installs before starting the migration in Section 2.
• Fifteen minutes to run the scan in Section 9, even if you don't plan to act on anything else in this guide yet.

1. The headline change: Docker-based self-hosting only

n8n 3.0 drops npm and npx installs; any OCI container runtime or orchestrator (Docker, Podman, Kubernetes, Nomad) that runs the official image is fine. This isn't a recommendation shift — it's the removal of an install method. An instance running npm or npx n8n will not be able to upgrade in place to 3.0.

n8n's guidance here is short: if you run n8n with npm or npx n8n, move to a Docker-based deployment before you upgrade, and for local installs Docker Compose is expected to be the easiest path. n8n has not yet published step-by-step migration tooling for this — the breaking-changes page notes that guidance is still coming. Section 2 gives you a path that works today, using commands already documented in the n8n CLI. This also covers anyone running n8n under PM2 on top of an npm install — the install method is what's removed, regardless of what supervises the process.

2. Migrating off npm, npx, and PM2

If your instance runs on npm, npx n8n, or npm under PM2, here's the migration path. It uses n8n's built-in export and import CLI commands, which already work in 2.x, so you can do this well before 3.0 ships and cut over on your own schedule.

Step 1: Export workflows and credentials from the existing instance.

# Run on the existing npm/npx/PM2 host
n8n export:workflow --all --output=export/workflows.json --pretty
n8n export:credentials --all --output=export/credentials.json --pretty

Credentials export in their encrypted form by default. You'll need the source instance's N8N_ENCRYPTION_KEY on the destination for the import to decrypt them — that's the whole reason the key has to match, not a separate step you can skip.

Step 2: Find the existing encryption key.

# npm install: check the config file or your process environment
cat ~/.n8n/config | grep -i encryptionKey
# or, if you set it as an environment variable:
echo "$N8N_ENCRYPTION_KEY"

Write this value down. Losing it between export and import makes the credentials export unreadable.

Step 3: Stand up the Docker stack.

Use the reference stack from our Docker Compose guide. Before starting it, set N8N_ENCRYPTION_KEY in .env to the exact same value you found in Step 2:

N8N_ENCRYPTION_KEY=the-same-key-from-the-npm-install

Bring the stack up, but don't point any webhooks or DNS at it yet:

docker compose up -d

Step 4: Import workflows and credentials into the new container.

docker compose cp export/workflows.json n8n:/tmp/workflows.json
docker compose cp export/credentials.json n8n:/tmp/credentials.json
docker compose exec n8n n8n import:workflow --input=/tmp/workflows.json
docker compose exec n8n n8n import:credentials --input=/tmp/credentials.json

Step 5: Verify, then cut over.

Open the new instance's editor, confirm your workflows and credentials look right, and run each active workflow manually once if you can. Then update WEBHOOK_URL, N8N_HOST, and your DNS or reverse proxy to point at the Docker instance, and decommission the npm/PM2 host. Keep the old host stopped, not deleted, for a week.

3. Removed nodes and their replacements

n8n 3.0 removes three legacy nodes outright. Current replacements have existed for a long time; this just removes the fallback.

Removed	Replace with
Function node	Code node, Run Once for All Items mode
Function Item node	Code node, Run Once for Each Item mode
Item Lists node	Split Out, Aggregate, Sort, Limit, Remove Duplicates, or Summarize — pick the node matching the operation you were using

The Item Lists node bundled several operations into one node, so check which operation each instance performs before choosing its successor.

4. Execute Workflow node: old behavior removed

n8n 3.0 removes the Execute Workflow node's older behavior. n8n's breaking-changes page states this as a fact without describing the mechanics of what the old behavior was or what replaces it — that detail hasn't been published yet. If you have Execute Workflow nodes that predate n8n 2.0 and haven't been touched since, flag them for a manual re-check once n8n publishes the migration guidance this page promises, rather than assuming they'll behave identically after the upgrade.

5. AI Agent node: version 1 and its modes removed

Version 1 of the AI Agent node supported several agent type modes: SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent, and ReAct Agent. n8n 3.0 removes version 1 of the node along with all five modes.

If your workflows already use the current AI Agent node in Tools Agent mode, nothing changes — n8n's guidance is explicit that Tools Agent workflows continue to behave the same after the upgrade. The work is only for workflows still pinned to version 1.

For SQL Agent specifically, there's a direct replacement: pair a Postgres or MySQL tool sub-node with a current AI Agent node instead. For the other four modes, n8n's guidance is simply to update the workflow to the current AI Agent node version — it doesn't map each old mode to a new configuration, so budget time to rebuild and test the agent's prompt and tool set rather than expecting a drop-in swap.

6. $getPairedItem removed

n8n 3.0 removes the deprecated $getPairedItem expression helper. Use n8n's standard item-linking mechanism instead: the pairedItem property, or $("<node-name>").item to reach back into a specific node's output. If you have expressions calling $getPairedItem(...), they'll need to be rewritten before the upgrade — the helper won't fail gracefully, it will simply not exist.

7. Tighter security defaults

n8n 3.0 tightens several security defaults. n8n's own summary is short: tighter handling of risky resource names, more secure credential behavior, and key rotation enabled by default. None of the three has published mechanics yet — there's no specific list of which resource names become "risky" or what exactly changes in credential handling. Treat this as a pending hardening move, not a feature change, and re-test credential-heavy workflows after you upgrade rather than before.

The one item in this section with concrete numbers is the Compression node. Its decompression limits drop from the current defaults:

• N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES drops from 2 GiB to 256 MiB.
• N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES drops from 5,000 to 1,000.

If any workflow decompresses archives larger than 256 MiB or with more than 1,000 entries, set both variables explicitly to their previous values before upgrading:

N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=2147483648
N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=5000

Setting these preserves current behavior; leaving them unset means large or entry-heavy archives will start failing where they didn't before.

8. Retired capabilities

Three things go away outright in 3.0:

• Chat Hub is retired.
• Workflow import from URL in the editor is removed. Other import paths keep working: copy-paste, Import from File in the editor's UI menu, the CLI (n8n import:workflow), and the n8n API. Switch any automation that pushes a URL into the editor's import field to the API or CLI instead.
• Non-functional nodes are removed. n8n hasn't published which nodes this covers — the phrase implies nodes that no longer work against their target service or API, not a named list yet.

9. Finding affected workflows today

Before you write any shell script, check Settings → Migration Report — the same admin tool described in our n8n 2.0 upgrade guide. It already scans the instance for Workflow and Instance Issues at Critical, Medium, and Low severity, with a Refresh button to re-scan, and it needs no shell access — it's the fastest first pass. It predates 3.0, though, so treat the jq scan below as the complement: it targets the specific 3.0-era node types (the removed nodes, AI Agent v1) that the report may not flag yet.

You don't need to wait for 3.0 to find out if you're affected. Export your workflows and scan the JSON for the node types this guide covers: n8n-nodes-base.function, n8n-nodes-base.functionItem, n8n-nodes-base.itemLists, and version 1 of the AI Agent node (n8n-nodes-langchain.agent with typeVersion 1).

n8n export:workflow --all --separate --output=export/

Then run this over the export directory:

jq -r '.nodes[] | select(.type=="n8n-nodes-base.function" or .type=="n8n-nodes-base.functionItem" or .type=="n8n-nodes-base.itemLists" or (.type=="n8n-nodes-langchain.agent" and .typeVersion==1)) | .type' export/*.json | sort | uniq -c

The output is a count of each affected node type across every exported workflow. Zero output means none of your workflows use these nodes; anything else is your inventory.

10. A 90-day timeline

Work backward from October 2026 using n8n's confirmed changes, not the parts still pending.

• Now: inventory. Run the scan in Section 9 against every environment you run — production, staging, anything with active credentials. Note which workflows use the Function, Function Item, or Item Lists nodes, and which use AI Agent version 1 in a non-Tools-Agent mode.
• 30 days: move installs to Docker. If any instance still runs on npm, npx n8n, or PM2, follow Section 2 and cut it over. Do this well before the node-level work in the next step — you want to be testing node replacements on the deployment model you'll actually run in production.
• 60 days: replace nodes. Work through the table in Section 3 and the AI Agent guidance in Section 5, workflow by workflow. Rewrite any $getPairedItem expressions found during the scan. Set the Compression node environment variables from Section 7 if you rely on the current limits.
• Before release: pin your version and wait. Pin production to your current 2.x tag explicitly (this book's reference stack pins n8nio/n8n:2.38.1) rather than tracking stable. When 3.0.0 ships, let it sit for one or two patch releases before touching production — a first major release is exactly when this guide's vaguer sections (Section 4, most of Section 7, and the non-functional-nodes list in Section 8) will surface as real bug reports from other operators. Read those patch changelogs before you upgrade.

11. Troubleshooting Common Issues

Credential import fails or credentials show as unreadable. The destination N8N_ENCRYPTION_KEY doesn't match the source instance's key. Re-check the value from Section 2, Step 2, and re-run n8n import:credentials after correcting .env. There is no recovery path other than re-entering credentials by hand.

docker compose exec n8n n8n import:workflow returns a permissions or path error. The file didn't make it into the container, or landed somewhere the node user can't read. Confirm the docker compose cp step completed and re-check the path passed to --input.

A workflow that used the Function node behaves differently after switching to the Code node. The Function node ran once for all items by default; if you pick Run Once for Each Item without adjusting the script, logic that assumed access to the full input array will break. Match the mode to what the original node actually did, not just its name.

An AI Agent workflow stops producing tool calls after upgrading from version 1. This usually means the workflow used OpenAI Functions Agent, ReAct Agent, Plan and Execute Agent, or Conversational Agent mode, none of which carry forward. Rebuild it on the current AI Agent node in Tools Agent mode, re-attach the same tool sub-nodes, and re-test the prompt — treat it as a rebuild, not an upgrade.

The scan in Section 9 finds nothing, but you know a workflow uses an old node. Check that the export actually captured it — n8n export:workflow --all should include inactive and archived workflows, but a filtered export won't. Re-run without ID filters and confirm the file count matches your workflow count in the editor.

Compression node starts failing on archives that worked before. You upgraded without setting N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES and N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES. Set both to their prior defaults (2147483648 and 5000) and restart the container.

Further reading

• https://docs.n8n.io/changelog/v30-breaking-changes.md
• https://docs.n8n.io/deploy/host-n8n/install-options/install-with-npm.md
• https://docs.n8n.io/deploy/host-n8n/install-options/install-using-docker-compose.md
• https://docs.n8n.io/build/manage-workflows/export-and-import.md
• https://docs.n8n.io/changelog/v20-migration-tool.md

---

Not sure if a workflow will survive the jump to 3.0? Post it in the House of Loops community and get eyes on it fast, or join the free weekly workflow list and get one delivered to your inbox every week.