n8n 3.0 Upgrade Guide: What Breaks, the Migration Report, and a Checklist Before Stable Lands

n8n 3.0 is a breaking-changes release: self-hosted n8n must run on Docker, a long list of legacy nodes is gone, several defaults get stricter, and the upgrade is one-way. n8n released the 3.0.0 beta on October 27, 2026 and says the stable release "follows in early December." Before you upgrade, n8n's own advice is to update to the latest 2.x, open Settings > Migration Report, fix or dismiss everything it flags, take a full backup, and upgrade a test instance before production.

If you self-host n8n, the stable release will put this question on your desk in a few weeks, so it is worth doing the prep now while 2.x is still the default. This guide covers what changes in n8n 3.0 (quoted from n8n's breaking-changes docs, read on November 10, 2026), who has to act, how the Migration Report works, and a step-by-step upgrade checklist for a self-hosted instance.

Status on November 10, 2026: n8n's Docker docs list the current stable as 2.47.3. Every 3.x build on n8n's GitHub releases page (3.0.0, 3.0.1, 3.1.0, and 3.2.0, which came out today) is marked as a pre-release. Stable 3.0 has not shipped yet. This post will be updated when it does.

When does n8n 3.0 come out?

The beta is out now and stable is planned for early December 2026. n8n has not published an exact stable date, so treat anything more precise than "early December" as a guess until it appears in the release notes.

Two of those rows matter most for planning. You are not forced onto 3.0 in December, because 2.x keeps getting security and critical fixes for a year after stable. And if you are still on 1.x, your deadline is closer than the 3.0 one: support ends on December 31, 2026, and you have to go to 2.x first.

Who has to act before upgrading to n8n 3.0?

n8n says every edition gets the same changes: "Everything in 3.0 applies to self-hosted Community, Cloud, and Enterprise/Business." How much work you have depends on how you run it.

If you are still choosing between hosting models, our breakdown of self-hosted n8n vs n8n Cloud costs compares the two, and 3.0 takes npm off the table for the self-hosted side.

What breaks in n8n 3.0?

n8n groups the changes into deployment, removed nodes and helpers, behavior changes, security, configuration and retired capabilities. The full list with a fix for each item is on the v3.0 breaking changes page. Here is what most self-hosted teams will run into.

Deployment: Docker only

Self-hosted n8n 3.0 requires a Docker-based deployment. If you run n8n with npm or npx n8n, n8n's instruction is to "move to a Docker-based deployment before you upgrade to n8n 3.0." The fastest route it documents is a one-line setup script (curl -fsSL https://get.n8n.io | sh) that checks Docker, writes the config files and starts a new instance. For a team or production instance, n8n points to its Docker Compose guide, which runs n8n with Postgres instead of the bundled SQLite database.

Removed nodes and what replaces them

This is the part that breaks running workflows. In n8n's words: "Workflows that use a removed node fail when they run. If such a workflow is published, it doesn't activate when n8n 3.0 starts, so its triggers stop firing."

The list on n8n's page is longer (iCalendar, the binary data converters, Orbit, several vector store Insert/Load nodes and document loaders). Two other node changes are easy to miss:

• AI Agent node v1 is gone. That removes the SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent and ReAct Agent modes. The latest version replaces them all with Tools Agent. For SQL use cases, n8n suggests a Postgres or MySQL tool sub-node on a recent AI Agent node.
• Edit Image node v1 and v1.1 are gone. Version 2 uses a different image library, so n8n warns that "image output can change": Sigma is removed from blur, text placement can shift, and PNG and TIFF ignore the Quality setting. Test any workflow that resizes, blurs or adds text.

Expressions and the Code node

• $getPairedItem is removed. Use $('<node-name>').item, .itemMatching(<index>) or .pairedItem(<index>) instead.
• $evaluateExpression() is removed from the Code node. It only affected task runners in insecure mode, since secure mode (the default since 2.0) already rejected it.
• The Execute Sub-workflow node loses its Local File and URL sources (node versions 1.1 and older). Import the sub-workflow and select it from the database, or paste its JSON.
• The default Code node task timeout drops from 300 seconds to 60. Long-running Code node tasks fail unless you set N8N_RUNNERS_TASK_TIMEOUT.

Behavior changes that don't throw errors

These are the risky ones, because the workflow keeps running and produces different results:

• Always Output Data on If, Switch and other multi-output nodes now adds an empty item only when every output is empty. Before, each empty output got one, "so branches ran when they shouldn't have."
• Gmail Trigger versions 1 to 1.3 now behave like 1.4: Max Emails per Poll applies (default 10, up to 50), drafts are skipped unless Include Drafts is on, and scheduled emails, plus sent emails that aren't in the inbox, no longer trigger.
• In the Using Response Nodes mode, Chat Trigger WebSocket messages are JSON frames with a type field. Custom chat clients must parse JSON, and an embedded @n8n/chat widget needs version 1.31.0 or later.
• Webflow OAuth2 defaults the Legacy toggle to off, so new credentials, and existing ones that never saved a Legacy value, request v2 API scopes when you reconnect them.

Security defaults

• Slack API credentials need the signing secret. Workflows with a Slack Trigger fail to publish without it, and already published ones "don't activate after the upgrade and stop receiving events." Copy the Signing Secret from your Slack app's Basic Information page into the credential before you upgrade.
• Encryption key rotation is on by default. n8n's guidance here is "Nothing" beyond backing up the database. Existing credentials stay readable and are re-encrypted to the current key the next time each record is updated.
• The default SSRF block list grows by four ranges (including 100.64.0.0/10, the carrier-grade NAT range) when SSRF protection is enabled with the default block list. If a workflow calls an internal host in one of those ranges, add it to N8N_SSRF_ALLOWED_IP_RANGES or N8N_SSRF_ALLOWED_HOSTNAMES.
• Compression node limits drop from 2 GiB to 256 MiB decompressed and from 5,000 to 1,000 zip entries.

If you are already tracking n8n advisories, this fits next to our guide to self-hosted n8n security updates, which covers the patch side of running your own instance.

Configuration and environment variables

n8n says 2.x logs a deprecation warning at startup for each of these when your instance is affected, so your current container logs are a quick first check.

Retired features

Chat Hub is off by default in 3.0 (you can turn it back on for 3.x with chat-hub in N8N_ENABLED_MODULES, and n8n says 4.0 removes it). Import from URL is gone from the editor, the Ask AI tab is gone from the Code node, and on Enterprise the "Enable external secrets for project roles" setting is removed, so project editors and admins get external-secrets access by default unless you set up custom roles first.

How do you run the n8n Migration Report?

The Migration Report is the tool n8n built for this upgrade, and n8n's docs say to run it before you upgrade. It is available on every instance running 2.39 or later, under Settings > Migration Report. n8n recommends updating to the latest 2.x first because the report keeps improving: 2.45.4 added a project filter, 2.46.2 a project column and 2.46.3 a "How to fix" panel on each rule.

What it does, per n8n's v3.0 Migration tool docs:

• Lists affected workflows (Workflow issues tab) and instance-level settings (Instance issues tab, owners and admins only).
• Shows a progress bar of how many workflows are already compatible.
• Migrates some issues automatically, for example replacing a Cron node with a Schedule Trigger. Each fix is saved as a new workflow version, and "a published workflow keeps running its current version until you publish the new one."
• Suggests an owner per workflow, lets admins reassign, and emails owners if SMTP is set up.
• Lets you mark obsolete workflows "Won't fix", and offers that for anything that hasn't run in over 12 months.
• Exports a CSV with one row per issue.

Every issue carries one of five impact levels, and n8n says to work through them in this order:

Watch out: n8n says automatic migration "covers the node changes only, so check the workflow's output still matches what you expect." And an empty report isn't the finish line: n8n tells you to review the breaking-changes page "for changes the tool can't detect, then upgrade."

n8n 3.0 upgrade checklist for self-hosted instances

This is the order we would run it in on a Docker Compose instance. Steps 1, 3, 4, 5, 7 and 8 follow n8n's recommended path and Migration Report docs, and steps 2 and 6 come from its breaking-changes page. The CSV baseline, the version pinning in step 9 and step 10 are our own additions.

1. Update to the latest 2.x (2.47.3 on the stable channel today) and confirm the instance is healthy.
2. Read the startup logs for deprecation warnings. Each one maps to a configuration change above.
3. Open Settings > Migration Report as an owner or admin, select Refresh, and export the CSV so you have a baseline.
4. Fix "Upgrade blocked" and "Executions will fail" first. Sort by most runs so your busiest workflows get fixed before the long tail. Mark dead workflows "Won't fix."
5. Work the remaining issues, then refresh until no unresolved issues remain and the compatible count matches the total.
6. Work through the breaking-changes items that sit outside your workflows: add the signing secret to Slack credentials, update any embedded @n8n/chat widget to 1.31.0 or later, fix volume mounts for the binaryData to storage rename, and set any environment variables whose defaults change.
7. Take a full backup: the database, plus the ~/.n8n folder or volume. n8n stores the auto-generated encryption key there, and your saved credentials can't be decrypted without it. If you set N8N_ENCRYPTION_KEY yourself, keep a copy of that value too.
8. Upgrade a test or staging copy first. Restore the backup onto a separate instance, pin the 3.x image tag there, start it, and run your critical workflows end to end.
9. Upgrade production once stable 3.0 is out, pinning an exact version tag instead of latest so the change happens when you choose. On Docker Compose that is docker compose pull, docker compose down, docker compose up -d.
10. Watch the first day of executions, especially schedules, Slack and Gmail triggers, and anything behind If or Switch nodes with Always Output Data on.

Before you upgrade: there is no downgrade. n8n's FAQ says "Can I roll back? No. Take a full backup before upgrading; going back means restoring it." The backup in step 7 is your only way back.

Should you upgrade to n8n 3.0 now or wait for stable?

For production, our view is wait for stable and do the prep now. n8n's own blog asks you to try the beta "on a test instance first," and the 3.x builds are still marked as pre-releases on GitHub. Nothing new is forcing a production move either: 2.x gets security and critical fixes for 12 months after stable.

The prep itself shouldn't wait. The Migration Report runs on 2.x, its fixes are saved as new workflow versions without touching what's live, and it shows you the size of the job before you commit to a date. Teams on npm or npx should start the Docker move now, because the hosting move has to be finished before any 3.x upgrade can start. And anyone still on 1.x has a December 31, 2026 support deadline, which comes before the 3.0 decision.

When to hand the upgrade to someone else

A small instance with a handful of flagged workflows is a checklist job. It gets harder when you have hundreds of workflows with no clear owner, queue mode with workers, custom community nodes, or AI Agent workflows built on the old agent modes, where each one needs rebuilding and retesting.

That is the work our n8n development and support agency does on self-hosted instances: run the Migration Report, fix and test the flagged workflows on a staging copy, and upgrade production with a backup and a tested restore. If the audit turns up workflows worth rebuilding properly rather than patching, our custom workflow automation team scopes that separately. For ideas on what a clean 3.x setup can run, see our n8n workflow examples.

FAQ

When is the n8n 3.0 stable release?

n8n says the stable release "follows in early December" 2026, and it hasn't published an exact date. The 3.0.0 beta came out on October 27, 2026. On November 10, 2026, every 3.x build on n8n's GitHub releases page is still marked as a pre-release.

Can I still install n8n with npm after 3.0?

No. n8n 3.0 "no longer supports installations run using npm or npx n8n" and doesn't publish a runnable n8n package to npm. Self-hosted instances need Docker, and n8n offers a one-line setup script for people who liked how quick npx n8n was. Kubernetes and Helm deployments aren't affected by this change.

Can I roll back from n8n 3.0 to 2.x?

No. n8n says moving to 3.x is one way, and going back means restoring a full backup taken before the upgrade. Back up your database and the ~/.n8n folder, and test the upgrade on a separate instance first.

How long will n8n 2.x be supported?

For 12 months after the 3.x stable release, with security and critical bug fixes only. New features ship on 3.x. Version 1.x support ends on December 31, 2026, and there's no direct upgrade path from 1.x to 3.x.

Where is the n8n Migration Report?

It's under Settings > Migration Report on any instance running version 2.39 or later. n8n recommends updating to the latest 2.x first, because newer versions have the latest version of the report. Owners and admins see every workflow and instance setting, while other users see only the workflows they can edit.

Do my credentials and execution history carry over to n8n 3.0?

Yes, according to n8n's FAQ for the 3.0 release. The upgrade itself needs only a short restart. Slack credentials are the exception to plan for: they need a signing secret before workflows with a Slack Trigger will activate.

What happens to Function and Item Lists nodes in n8n 3.0?

They're removed, and workflows that still use them fail. Function becomes the Code node in "Run Once for All Items" mode, and Function Item becomes "Run Once for Each Item." Item Lists splits into Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize. The Migration Report can migrate many of these automatically. If you want a second pair of eyes on your report before you start, our n8n consulting review covers that.

---

Sources (all read November 10, 2026): n8n blog: Introducing n8n 3.0, n8n docs: v3.0 breaking changes, n8n docs: v3.0 Migration tool, n8n docs: Release notes, n8n docs: Install with Docker, n8n docs: Set a custom encryption key, n8n GitHub releases