Short answer. n8n 3.0 beta came out on 27 October 2026, and the stable release is planned for early December. Self-hosted n8n must run on Docker (npm and npx n8n installs are no longer supported), legacy nodes like Function, Cron and Item Lists are removed, and some defaults are stricter. Open Settings > Migration Report on 2.39 or later to see what you need to fix (n8n blog).
Our advice: don't upgrade yet, prepare now. 3.0 is mostly cleanup and safer defaults. Most workflows will be fine, and the ones that break are predictable: n8n's own report finds most of them.
When 3.0 ships, and do you need to upgrade now?
As of 28 Oct 2026, according to the n8n 3.0 announcement:
- Beta: 3.0.0, out on 27 October 2026.
- Stable: planned for early December. n8n hasn't given a specific day.
- 2.x support: after the stable release, 2.x gets security and critical bug fixes for 12 months. New features ship on 3.x only.
- Still on 1.x? Upgrade to 2.x first. There's no direct path from 1.x to 3.x, and support for 1.x ends on 31 December 2026.
- Who it applies to: self-hosted Community, Cloud, and Enterprise/Business.
- Cloud: you can try it by picking 3.0.0 Beta (early access) when you change your n8n version.
The part that matters most: the upgrade is one way. There's no going back to 2.x. Rolling back means restoring the full backup you took before upgrading. Credentials and execution history carry over, and downtime is a short restart, like any upgrade.
Start here: the Migration Report
Every instance on 2.39 or later has a Migration Report under Settings > Migration Report. Update to the latest 2.x first, because it has the newest version of the report (n8n blog).
How it works, from the v3.0 migration tool docs:
- Two tabs. Workflow issues lists the changes that affect your workflows. Instance issues lists config changes such as environment variables. Only owners and admins see the Instance tab. Other users see the workflows they can edit.
- Five impact levels. Fix them in this order:
| Impact | What it means |
|---|---|
| Upgrade blocked | The upgrade can't proceed, or the instance may not start after it |
| Executions will fail | Affected workflows or the instance fail after the upgrade |
| Executions might fail | A default changes, so executions might fail |
| Behavior changes | Workflows keep running but behave differently |
| Capability removed | Executions aren't affected, but a feature you use is gone |
- A Migrate button appears for issues n8n can fix itself, for example replacing a Cron node with a Schedule Trigger. The result is saved as a new workflow version. Your published version keeps running until you publish the new one. Test it first: the migration only covers the node changes.
- "Won't fix" is for obsolete workflows. If a workflow hasn't run in over 12 months, a banner offers to mark it.
- Notify owners emails the person responsible (needs SMTP). Export CSV gives you a summary to share.
One warning from the docs: an empty report doesn't mean zero risk. Read the v3.0 breaking changes page for the changes the tool can't detect.
If you run n8n with npm or npx: move to Docker first
From 3.0, self-hosted n8n needs a Docker-based deployment. n8n 3.0 doesn't support npm or npx n8n installs and doesn't publish a runnable n8n package to npm (breaking changes). Kubernetes and Helm deployments aren't affected (n8n blog). If you already run your own Docker Compose file, you don't need to switch.
Your options, from n8n's docs:
- Fastest: the one-line setup, which checks Docker, writes the config files and starts a new instance:
curl -fsSL https://get.n8n.io | sh
- For a team or production instance: Docker Compose with Postgres. For a full server walkthrough, see our guide to set up n8n with Docker Compose on a VPS.
Both create a fresh instance, so your workflows don't come along by themselves. n8n's backup docs describe moving workflows and credentials between instances with the CLI:
n8n export:workflow --backup --output=backups/workflows/
n8n export:credentials --backup --output=backups/credentials/
Then import them on the new instance. Two catches from the same page. First, credentials only decrypt with the old key, unless you export them with --decrypted, which leaves them in plain text, so delete that file after the import. Second, a CLI export doesn't include users, execution history, variables or instance settings.
Our rule: change one thing at a time. Move to Docker on your current 2.x version, check that everything runs, and only then upgrade to 3.0.
Building community nodes? n8n-node dev now needs Docker or Podman (breaking changes).
If the upgrade makes you rethink your setup, see our take on n8n vs custom code.
Removed nodes and what replaces them
Workflows that use a removed node fail (breaking changes). The common ones:
| Removed | Use instead |
|---|---|
| Function | Code node, Run Once for All Items |
| Function Item | Code node, Run Once for Each Item |
| Item Lists | Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize |
| Cron, Interval | Schedule Trigger |
| HTML Extract | HTML node, Extract HTML Content |
| Read Binary File(s), Write Binary File | Read/Write Files from Disk |
| Read PDF | Extract from File, Extract From PDF |
| iCalendar | Convert to File, Convert to ICS |
| Workflow Trigger | n8n Trigger |
| OpenAI (legacy), OpenAI Assistant | OpenAI node (Assistant resource for assistants) |
| OpenAI Model | OpenAI Chat Model |
| AI Agent v1 modes (SQL, ReAct, Conversational and others) | Latest AI Agent (Tools Agent) |
More removals: Manual Chat Trigger, Convert to/from binary data, the legacy HTTP Request Tool, SerpApi, Orbit, Motorhead and Zep memory, older vector store Insert/Load nodes, and Edit Image versions 1 and 1.1. LangChain Code, SerpApi, Motorhead and Zep have no direct replacement. AI Transform nodes are migrated to Code nodes automatically on upgrade.
Two more removals catch people out:
- The
$getPairedItemexpression helper. Use$('Node name').iteminstead. - The Local File and URL sources in the Execute Sub-workflow node.
Check the full list for your instance.
Defaults that fail quietly
These break things later, at runtime. All from the v3.0 breaking changes page:
- Code node timeout drops from 5 minutes to 1 minute. Longer tasks fail. If you need more time, set it explicitly in seconds:
N8N_RUNNERS_TASK_TIMEOUT=300
- Slack needs a signing secret. The Slack API credential now requires it. If a workflow uses the Slack Trigger, add the secret before you upgrade. Otherwise the workflow won't publish and the trigger returns a 401 error. In your Slack app, open Basic Information, copy the Signing Secret, paste it into the credential, then publish the workflow again.
- Unverified community packages are off.
N8N_UNVERIFIED_PACKAGES_ENABLEDnow defaults tofalse, and unverified nodes you've already installed stop loading. Set it totrueor move to verified nodes. - Storage folder renamed.
~/.n8n/binaryDatabecomes~/.n8n/storage, and n8n won't start if both exist. If you mount a volume at the old path, change the mount or setN8N_STORAGE_PATH. - In-memory binary data mode is gone. Instances that still use it switch to
filesystem. Check your disk has room. - Lower Compression node limits: 256 MiB instead of 2 GiB, and 1,000 entries instead of 5,000.
- Larger SSRF block list, if SSRF protection is on, as long as
defaultstays inN8N_SSRF_BLOCKED_IP_RANGES. It now includes100.64.0.0/10, among others. - Queue mode: manual executions always run on workers, and
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERSis removed. - Behavior changes: Always Output Data on If and Switch nodes now adds an empty item only when every output is empty. Gmail Trigger versions below 1.4 now run as 1.4, so drafts are skipped unless you turn on Include Drafts.
- Encryption key rotation is on by default. There's nothing to do except back up first.
- Retired: Chat Hub is off by default (add
chat-hubtoN8N_ENABLED_MODULESto keep it on 3.x). Import from URL and the Code node's Ask AI tab are gone.
Upgrade checklist
- 1. Update to the latest 2.x. You get the newest Migration Report.
- 2. On npm or npx? Move to Docker, still on 2.x. Confirm everything runs.
- 3. Work through the Migration Report. Fix "Upgrade blocked" and "Executions will fail" first, then the rest. Mark obsolete workflows "won't fix".
- 4. Set the environment variables you depend on: task timeout, community packages, storage path, Compression limits.
- 5. Add the Slack signing secret to every Slack API credential used by a Slack Trigger.
- 6. Take a full backup: the
.n8nfolder or volume, plus your Postgres database if you use one. The.n8nfolder holds the encryption key. Without it, restored credentials can't be decrypted (backup docs). - 7. Upgrade a test or staging copy first. Run your key workflows and triggers.
- 8. Upgrade production with a pinned version, not
latest. n8n's own Docker Compose setup pins the image through a version variable:
image: n8nio/n8n:${N8N_VERSION}
FAQ
When is n8n 3.0 released?
The beta came out on 27 October 2026, and n8n plans the stable release for early December. After the stable release, 2.x keeps getting security and critical bug fixes for 12 months, so you don't have to upgrade on day one.
Can I still run n8n with npx or npm?
Not on 3.0. Self-hosted n8n 3.0 needs a Docker-based deployment, and n8n no longer publishes a runnable n8n package to npm. Kubernetes and Helm setups aren't affected. Move to Docker on your current 2.x version first, check it works, then upgrade.
How do I know if my workflows will break?
Update to the latest 2.x (2.39 or later) and open Settings > Migration Report. It lists affected workflows and instance settings by impact level, and can migrate some nodes automatically. An empty report is a good sign, but still read n8n's breaking changes page for things the tool can't detect.
Can I roll back from n8n 3.0 to 2.x?
No. The upgrade is one way. Going back means restoring the full backup you took before upgrading: the .n8n folder with its encryption key, plus your database if you use Postgres. Test 3.0 on a copy first.
What replaces the Function and Cron nodes?
The Function node becomes the Code node in Run Once for All Items mode. Function Item becomes the Code node in Run Once for Each Item mode. Cron and Interval become the Schedule Trigger. The Migration Report can convert Cron to Schedule Trigger for you.
Why do my Code nodes time out after upgrading?
The default task runner timeout dropped from 5 minutes to 1 minute, so longer Code node tasks fail. Set N8N_RUNNERS_TASK_TIMEOUT to a higher value in seconds, for example 300 to keep the old limit, before you upgrade.
Do I need to change my Slack credentials?
Yes. Add the signing secret from your Slack app's Basic Information page to the Slack API credential. If a workflow uses the Slack Trigger, do it before upgrading, or it won't publish and stops receiving events. For other Slack workflows, add it the next time you edit the credential.
