n8n 3.0 breaking changes: what to fix before you upgrade

n8n 3.0 is scheduled for October 2026, according to n8n's own breaking changes page. The three changes that will affect the most people: self-hosted n8n must run on Docker (installs with npm or npx n8n are no longer supported), more than 35 legacy nodes are removed, and several defaults get stricter, including a 1-minute timeout for Code node tasks.

Most instances can be made ready in an afternoon. Start with Settings > Migration Report in your current 2.x instance, which lists the workflows and settings that need attention, then work through the checklist below.

The short version

• npm and npx installs end. Move self-hosted n8n to Docker (Docker Compose for local setups) before upgrading.
• Legacy nodes are removed. Function, Function Item, Item Lists, Cron, Interval, Read Binary File(s), Write Binary File, Read PDF, HTML Extract, iCalendar, the legacy OpenAI nodes and several older AI nodes are gone. Most have a direct replacement.
• AI Agent version 1 is removed, along with its SQL, Conversational, OpenAI Functions, Plan and Execute, and ReAct modes.
• Expression and Code node helpers go: $getPairedItem and $evaluateExpression() in the Code node.
• Stricter defaults: Code node tasks time out after 60 seconds instead of 300, unverified community packages are off, the SSRF block list grows, and the Compression node accepts smaller archives.
• Retired features: Chat Hub is off by default, and importing a workflow from a URL in the editor is removed.

Who needs to act

Docker becomes mandatory for self-hosted n8n

n8n 3.0 "will no longer support installations run using npm or npx n8n." The 3.0 notes for node developers go further: n8n 3.0 "doesn't publish a runnable n8n package to npm," so there will be no npm package to upgrade to.

If you already run the official Docker image, nothing changes here. If you run n8n directly on a server with npm, under a process manager such as PM2 or systemd, you need to migrate first. n8n expects Docker Compose to be the easiest path for local installations and says step-by-step migration guidance is coming. The core of any migration:

1. Stop n8n and back up your database and the ~/.n8n folder. n8n generates an encryption key on first launch and saves it in that folder's settings file, unless you set N8N_ENCRYPTION_KEY yourself. Without that key, your saved credentials cannot be decrypted.
2. Run the official image (docker.n8n.io/n8nio/n8n) pinned to the same version you run today, with the old ~/.n8n folder mounted at /home/node/.n8n, the same database settings and the same encryption key.
3. Confirm workflows and credentials work, then upgrade the pinned version.

Changing the install method and the major version at the same time makes problems hard to trace, so do the Docker move on your current 2.x version first.

Removed nodes and their replacements

The legacy LangChain Code node is also on the removal list, without a replacement named yet.

The AI Transform node is handled differently: on upgrade, n8n converts existing AI Transform nodes into Code nodes with the same generated JavaScript, so those workflows keep working. You just can't add new AI Transform nodes.

AI Agent and chat changes

Version 1 of the AI Agent node is removed, together with its agent type modes: SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent and ReAct Agent. Update those nodes to the latest AI Agent version. Workflows already using Tools Agent behave the same after updating. For SQL Agent use cases, n8n recommends a Postgres or MySQL tool sub-node connected to a recent AI Agent node.

The Chat Trigger WebSocket used in the Using Response Nodes response mode now sends every frame as a JSON object with a type field (heartbeat, continue, error, message or with-buttons). A text reply looks like this:

{ "type": "message", "text": "Hi! How can I help?" }

Clients acknowledge heartbeats with { "type": "heartbeat-ack" }. If you embed n8n's chat widget (@n8n/chat) yourself, update it to version 1.31.0 or later before upgrading n8n. The hosted chat page needs no changes.

Chat Hub is turned off by default in 3.0 and will be removed in n8n 4.0. Your chat sessions, agents and messages stay in the database. To keep it running during the 3.x line, add chat-hub to N8N_ENABLED_MODULES while keeping any modules you already enable, for example N8N_ENABLED_MODULES=agents,chat-hub. This is separate from the new Agents feature introduced in n8n 2.40, which is not being retired.

Expressions, Code node and sub-workflows

• $getPairedItem is removed. Use standard item linking instead, such as the pairedItem property or $("Node name").item.
• $evaluateExpression() is removed from the Code node. Since 2.0, Code nodes run on task runners in secure mode, where this call already fails; only instances running N8N_RUNNERS_INSECURE_MODE=true were still using it. Evaluate the expression in a field of an earlier node, such as Edit Fields (Set), and read the result from the incoming item. $evaluateExpression() keeps working in normal {{ }} expression fields.
• Execute Sub-workflow loses the Local File and URL sources. Only node versions 1.1 and older offered them, and those nodes now fail. Import the sub-workflow and select it with the Database source, or paste its JSON with Define Below.
• Always Output Data behaves differently on multi-output nodes. On nodes such as If and Switch, n8n now adds an empty item only when every output is empty. Before, each empty output got its own empty item, so branches could run when they shouldn't. Review flagged nodes and confirm the setting still matches what you want.

Node behavior changes

Gmail Trigger versions 1 to 1.3 now run with version 1.4 behavior:

• Max Emails per Poll applies to every poll: 10 by default, up to 50. Remaining emails are picked up in later polls.
• Drafts are skipped unless you turn on the Include Drafts filter. Versions 1 and 1.1 included drafts by default.
• Sent emails that aren't in the inbox, and scheduled emails, no longer trigger the workflow.

If a workflow relied on sent or scheduled emails, n8n suggests replacing the trigger with a Schedule Trigger followed by the Gmail node's Get Many messages operation.

Webflow OAuth2 API credentials now default to the Webflow v2 API scopes. Connected credentials keep working, but if you still use the deprecated Webflow v1 Data API, turn on the Legacy toggle before you reconnect the credential.

Configuration and environment variables

For many of these settings, n8n 2.x already logs a deprecation warning at startup when your instance is affected, so check your logs before upgrading.

Retired features

• Chat Hub: off by default, removed in 4.0 (see above).
• Import from URL in the workflow editor is removed. Copy-paste, Import from File, the CLI and the n8n API still work.
• Enable external secrets for project roles (Enterprise) is removed. Project editors and admins get external-secrets access in their projects by default; use custom project roles to restrict it.
• The Ask AI tab in the Code node is removed.

For community node developers

• defaults.color is removed from the node description. Nodes that set it still work, but Font Awesome icons appear in a neutral color. Switch to an SVG or PNG file icon.
• n8n-node dev now runs n8n in a container, so it needs Docker or Podman. To use your own instance, run n8n-node dev --external-n8n and start that instance with N8N_DEV_RELOAD=true. Pin a version with --n8n-image docker.n8n.io/n8nio/n8n:<version>.
• Test workflows and credentials now live in a per-image container volume (n8n-node-cli-data-<image>), not in ~/.n8n-node-cli/.n8n. Export test workflows you want to keep before upgrading the CLI.
• --custom-user-folder only applies together with --external-n8n.

n8n-node build, lint, release and npm create @n8n/node are unchanged.

How to prepare: a step-by-step checklist

1. Pin your version. Use an exact image tag such as n8nio/n8n:2.41.4 rather than a moving tag, so nothing upgrades to 3.0 before you are ready. n8n has recommended pinning exact versions since 2.0.
2. Back up. Database dump, the ~/.n8n folder and your encryption key. Test that the backup restores.
3. Move to Docker if you run n8n with npm or npx, while still on 2.x.
4. Open Settings > Migration Report (global admins only). Fix Critical issues first, then Medium, then Low, and re-scan until the counts reach zero. Check both the Workflow issues and Instance issues tabs.
5. Read your startup logs for deprecation warnings and set any environment variables whose old defaults you rely on.
6. Replace removed nodes using the table above, and update AI Agent nodes still on version 1.
7. Test on a copy. Restore your backup into a staging instance, upgrade it to 3.0 when it is released, and run your most important workflows end to end.
8. Upgrade production, then watch failed executions closely for the first days.

When is n8n 3.0 released?

n8n's documentation says 3.0 is "scheduled for October 2026." n8n has not published a specific date in its docs as of October 1, 2026. Until then, keep your instances on a pinned 2.x version, run the Migration Report and fix what it finds. We will update this guide, and cover the release itself in our news section, as soon as n8n publishes more detail.