Key takeaways
- n8n 3.0.0 was released as a beta on October 27, 2026, and 3.0.1 followed on October 28. n8n plans the stable 3.x release for early December. There is no way back to 2.x after you upgrade.
- Self-hosted n8n 3.0 runs on Docker only. n8n no longer publishes a runnable package to npm, so
npm install -g n8nandnpx n8nsetups must move to Docker first. - Workflows that use a removed node fail. The big ones: Function, Function Item, Item Lists, Cron, Interval, Read Binary File(s), the legacy OpenAI node and version 1 of the AI Agent node. Most have a direct replacement.
- Quiet breakers: Slack Trigger needs a signing secret, unverified community nodes stop loading, the Code node task timeout drops from 5 minutes to 1, and Gmail Trigger versions below 1.4 change behavior.
- Path: update to the latest 2.x, clear Settings > Migration Report, take a full backup, upgrade a test copy, then production. 2.x keeps getting security and critical fixes for 12 months after the 3.x stable release, so there is no need to rush.
The short answer
If you are on n8n 2.x, the only urgent step today is the October 28 security patch (2.45.5 on the stable track). The 3.0 upgrade itself can wait. n8n's announcement describes 3.0 as a release "with a focus on reliability, stability, and security" that does not add big new features, and says that 2.x will keep getting security and critical bug fixes for 12 months after the 3.x stable release. What you should do now is open Settings > Migration Report on the latest 2.x and start clearing what it flags.
If something already broke because you moved to 3.0, find the failing node in the execution log and match it against the table below. Every row comes from n8n's official v3.0 breaking changes page, checked on October 28, 2026.
Still on 1.x? There is no direct path from 1.x to 3.x. Upgrade to 2.x first (our n8n 2.0 breaking changes guide covers that step), then to 3.x. n8n says support for 1.x ends on December 31, 2026.
Release timeline and support windows
Dates from n8n's 3.0 announcement, its GitHub releases and the October 28 security update.
| Date | What happened | Source |
|---|---|---|
| October 23, 2026 | n8n announces version 3.0 on its community forum | n8n community announcement |
| October 27, 2026 | n8n@3.0.0 released as a pre-release (beta) | n8n GitHub releases |
| October 28, 2026 | n8n@3.0.1 released; the same day's security update lists 3.0.1 as the patched 3.x version | n8n GitHub releases, n8n security update |
| Early December 2026 | Planned stable 3.x release | n8n community announcement |
| December 31, 2026 | Support for 1.x ends | n8n community announcement |
| 12 months after 3.x stable | 2.x stops getting security and critical bug fixes | n8n community announcement |
Every n8n 3.0 breaking change: symptom and fix
Grouped the way n8n groups them. Environment variables go in your Docker Compose environment: block or your .env file.
| Change | What you see after upgrading | Fix |
|---|---|---|
| Docker required for self-hosting; no runnable npm package | There is no 3.x version to install with npm or npx | Move to Docker on 2.x first (see below), then upgrade |
| Legacy nodes removed (Function, Function Item, Item Lists, Cron, Interval, HTML Extract, iCalendar, Read/Write Binary File(s), Read PDF, Workflow Trigger and more) | Workflows that use them fail | Swap each for its replacement (table below). The Migration Report can migrate some automatically |
| Legacy AI nodes removed (legacy OpenAI, OpenAI Assistant, OpenAI Model, HTTP Request Tool, Manual Chat Trigger, Motorhead and Zep memory, split vector store Insert/Load nodes) | AI workflows fail to run | Use the current OpenAI node, OpenAI Chat Model, an HTTP Request node on the agent's Tool input, Chat Trigger, and the single vector store node per store (Motorhead and Zep: see below) |
| AI Agent node version 1 and its older modes removed (Conversational, ReAct, SQL Agent and others) | Old agents stop working | Update the node to the latest version; it uses Tools Agent. For SQL Agent, pair a Postgres or MySQL tool with a recent AI Agent |
$getPairedItem removed | Expressions that call it fail when the node runs | Use $('Node').item, .itemMatching(i) or .pairedItem(i) |
$evaluateExpression() removed from the Code node | Fails only if you ran task runners with N8N_RUNNERS_INSECURE_MODE=true | Evaluate the expression in an Edit Fields (Set) node before the Code node |
| Execute Sub-workflow: Local File and URL sources removed | The node errors (only node versions 1.1 and older offered these) | Import the sub-workflow and select it with the Database source, or paste its JSON |
| Edit Image node versions 1 and 1.1 removed | Workflow errors; after updating, blur, text placement and resize output can differ | Update to node version 2 and compare the images it produces |
| Always Output Data on If, Switch and other multi-output nodes | Empty branches no longer run; an empty item is added only when every output is empty | Review each flagged node and set the option to match your intent |
| Gmail Trigger versions 1 to 1.3 run as 1.4 | Max 10 emails per poll by default (up to 50), drafts skipped, sent and scheduled emails no longer trigger | Turn on Include Drafts if needed; for sent mail use a Schedule Trigger plus Gmail Get Many |
| Slack API credential requires the signing secret | Slack Trigger workflows fail to publish and the trigger answers 401 | Copy the Signing Secret from your Slack app's Basic Information page into the credential, then publish again |
| Webflow OAuth2 Legacy toggle off by default | Reconnecting a Webflow credential fails for v1 API apps | Turn on Legacy before reconnecting if you still use the Webflow v1 API |
| Chat Trigger WebSocket now sends JSON frames | A custom chat client shows raw JSON or ignores replies | Parse every frame as JSON and switch on type; update @n8n/chat to 1.31.0 or later |
Unverified community nodes off (N8N_UNVERIFIED_PACKAGES_ENABLED → false) | Installed unverified community nodes stop loading | Set N8N_UNVERIFIED_PACKAGES_ENABLED=true or move to verified nodes |
Task runner timeout cut (N8N_RUNNERS_TASK_TIMEOUT 300 → 60 seconds) | Long Code node tasks fail after one minute | Set N8N_RUNNERS_TASK_TIMEOUT explicitly |
| Larger default SSRF block list (only with SSRF protection on) | Requests to 100.64.0.0/10 (carrier-grade NAT, used by some VPNs) and three IPv6 ranges fail | Allow them with N8N_SSRF_ALLOWED_IP_RANGES or N8N_SSRF_ALLOWED_HOSTNAMES; keep default in the block list |
| Compression node limits lowered (2 GiB → 256 MiB unpacked, 5,000 → 1,000 zip entries) | Large archives fail to decompress | Set N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=2147483648 and N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=5000 |
~/.n8n/binaryData renamed to ~/.n8n/storage | n8n refuses to start if both folders exist | Mount volumes at storage or set N8N_STORAGE_PATH; merge the folders if both exist |
| In-memory binary data mode removed | N8N_DEFAULT_BINARY_DATA_MODE=default switches to filesystem, so binary data is now written to disk | Set filesystem, s3, azure or database and check free disk space |
| Queue mode: manual executions always run on workers | Workers use more memory | Remove OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS and review worker memory |
Removed variables: N8N_DB_PING_TIMEOUT, N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION | The setting is ignored | Use DB_PING_TIMEOUT_MS; move pre-execute hook alerts into the hook itself |
| Encryption key rotation on by default | Nothing visible; records are re-encrypted with the current key when next updated | No action beyond a backup |
| Chat Hub off by default (removed in 4.0) | The Chat section disappears | Add chat-hub to N8N_ENABLED_MODULES, keeping the modules you already enable |
| Retired: Import from URL in the editor, Ask AI tab in the Code node, a project-roles setting for external secrets (Enterprise) | Menu options are gone | Import from file, paste, the CLI or the API. On Enterprise, create custom project roles before upgrading, or every project editor and admin gains external-secrets access |
Community node authors have a few more items (the defaults.color property and the n8n-node dev loop now needing Docker or Podman). They are listed on the same docs page.
Removed nodes and what replaces them
On older instances this is usually the biggest item, because Function nodes and Cron triggers date from early n8n versions. Replacements, per n8n's docs:
| Removed node | Replace with |
|---|---|
| Function | Code node, mode Run Once for All Items |
| Function Item | Code node, mode Run Once for Each Item |
| Item Lists | Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize, matching the operation you used |
| Cron, Interval | Schedule Trigger |
| HTML Extract | HTML node, Extract HTML Content |
| iCalendar | Convert to File, Convert to ICS |
| Convert to/from binary data | Convert to File or Extract from File |
| Read Binary File, Read Binary Files, Write Binary File | Read/Write Files from Disk |
| Read PDF | Extract from File, Extract From PDF |
| Workflow Trigger | n8n Trigger |
| OpenAI (legacy), OpenAI Assistant | OpenAI node (Assistant resource for assistants) |
| OpenAI Model | OpenAI Chat Model |
| HTTP Request Tool (legacy) | HTTP Request node connected to the AI Agent's Tool input |
| Manual Chat Trigger | Chat Trigger |
| Chat Messages Retriever | Chat Memory Manager, or load previous sessions in Chat Trigger |
| Binary, JSON and GitHub Document Loaders | Default Data Loader (fetch GitHub content with the GitHub node first) |
| In Memory, Pinecone and Supabase Insert/Load nodes | Simple, Pinecone or Supabase Vector Store, choosing the operation inside the node |
| LangChain Code, Motorhead, Zep, SerpApi, Orbit | No direct replacement: rebuild with another memory or vector store node, call SerpApi with an HTTP Request tool, or remove (Orbit shut down) |
Two clarifications from n8n staff on the announcement thread: the regular HTTP Request node is not removed, only the legacy HTTP Request Tool node. And the removed Workflow Trigger is not the Manual Trigger or the Execute Workflow Trigger you use for sub-workflows. The AI Transform node is converted to a Code node automatically on upgrade, with the same generated JavaScript.
Related: n8n's October 28 security update lists a high-severity advisory titled "Deprecated Code Nodes Allow Code Execution in the n8n Main Process", fixed in 2.45.5 (stable), 2.46.1 (beta), 3.0.1 and 1.123.89. The fix is the patched version, so update within your current major line first. Replacing deprecated code nodes also removes that attack surface.
Use the Migration Report first
The Migration Report is n8n's built-in compatibility scan. It is available under Settings > Migration Report from version 2.39, and the latest 2.x has the newest version of it. Unlike the 2.0 report, every user can open it: admins see every workflow plus an Instance issues tab, other users see the workflows they can edit.
- Read the progress bar. It shows how many workflows are already compatible with 3.0.
- Start with "Upgrade blocked" (the upgrade can't proceed or the instance may not start), then "Executions will fail". The other levels are "Executions might fail", "Behavior changes" and "Capability removed".
- Use Migrate where it appears. For issues n8n can fix automatically, select the workflows and click Migrate. Each fix is saved as a new workflow version for you to review and publish.
- Mark the rest. Fix them by hand, or mark them Won't fix (for example, a workflow you will delete). Admins with SMTP set up can assign owners and click Notify owners.
- Refresh until both tabs are clean. n8n re-checks a workflow every time you save it.
Behavior-change items, like the Gmail Trigger and Always Output Data rows above, do not stop a workflow from running. They change what it does, so test those workflows with real data rather than trusting a green run.
If you run n8n with npm: move to Docker on 2.x first
n8n's docs say an existing npm install "keeps working for now", but n8n 3.0 is not published as a runnable npm package, so there is nothing to upgrade to. Do the move as its own step, on the same 2.x version you run today, so that you only change one thing at a time.
For a brand-new instance, n8n recommends its one-line setup, curl -fsSL https://get.n8n.io | sh. n8n's docs say it is meant for fresh installs, not for converting an existing setup, so for an existing npm instance with the default SQLite database we would carry the data folder across instead:
n8n --version # note it, e.g. 2.45.5
# stop n8n (systemd, pm2 ...), then back up the whole folder
tar czf ~/n8n-npm-backup-$(date +%F).tgz -C ~ .n8n
docker volume create n8n_data
docker run --rm --user root --entrypoint sh \
-v n8n_data:/data -v ~/.n8n:/src:ro docker.n8n.io/n8nio/n8n:2.45.5 \
-c "cp -a /src/. /data/ && chown -R node:node /data" # the image runs as user node
docker run -d --name n8n -p 5678:5678 \
-v n8n_data:/home/node/.n8n \
docker.n8n.io/n8nio/n8n:2.45.5 # SAME version as beforeThe .n8n folder holds the config file with your credential encryption key and, with SQLite, the database itself, which is why it moves as one piece. Carry over every environment variable your service used (above all N8N_ENCRYPTION_KEY if you set one, plus WEBHOOK_URL and your database settings if you use Postgres). Check that workflows, credentials and webhooks work in the container, and only then plan the 3.0 upgrade. If you already use your own Docker Compose file, you do not need to switch to the one-line setup.
Pre-upgrade checklist
- Update to the latest 2.x patch of your line. As of October 28 that is 2.45.5 on the stable track. It has the newest Migration Report and the latest security fixes.
- Clear the Migration Report, both tabs.
- Set new defaults on purpose. If you need old values, set them in your environment before upgrading:
N8N_RUNNERS_TASK_TIMEOUT,N8N_UNVERIFIED_PACKAGES_ENABLED, the two Compression limits, andN8N_ENABLED_MODULESif you use Chat Hub. - Add the Slack signing secret to any Slack API credential used by a Slack Trigger.
- Check volume mounts. If you mount a volume at
/home/node/.n8n/binaryData, change it to/home/node/.n8n/storageor setN8N_STORAGE_PATH. - Take a full backup: the whole
.n8nfolder (orn8n_datavolume) and, on Postgres, a database dump. n8n's backup docs are clear that without the encryption key, a restored database can't decrypt your credentials. - Write down the exact current image tag and environment. That is your rollback target.
- Upgrade a test copy first, restored from that backup, and run your important workflows end to end.
In the commands below, n8n_data is the volume name from n8n's Docker docs. Docker Compose often prefixes it with the project name (for example myproject_n8n_data), so check with docker volume ls and use the real name, or you will back up an empty volume.
docker volume ls # find the real n8n volume name
docker compose stop n8n # stop before copying a SQLite database
mkdir -p ~/n8n-backup
docker run --rm -v n8n_data:/data -v ~/n8n-backup:/backup alpine \
tar czf /backup/n8n_data-$(date +%F).tgz -C /data .
# Postgres only (service named postgres; replace n8n with your DB user and database name):
docker compose exec -T postgres pg_dump -Fc -U n8n n8n > ~/n8n-backup/n8n-$(date +%F).dump
docker compose start n8nThe upgrade itself
Self-hosted with Docker Compose
Pin the exact version rather than a moving tag. On October 28, n8n's own security update listed 2.46.1 as the patched beta version and 3.0.1 as the patched 3.x version, so a beta tag does not necessarily mean 3.x. Pin 3.0.1 (or whatever the newest 3.x patch is when you upgrade).
This assumes your compose file uses image: docker.n8n.io/n8nio/n8n:${N8N_VERSION}. If the tag is written directly in the image: line, change it there instead.
N8N_VERSION=3.0.1 # in .env, exact version
docker compose pull
docker compose down
docker compose up -d
docker compose logs -f n8n # wait for database migrations to finishDo not interrupt the first start; it migrates the database. Then open the editor, confirm workflows and credentials are there, run each critical workflow once, and check that production workflows are still published. If you installed with n8n's one-line setup, its upgrade command is curl -fsSL https://get.n8n.io | sh -s -- --upgrade, and --version followed by a version number installs that specific version.
n8n Cloud
The instance owner opens the Cloud console, goes to Instance settings > Updates, picks 3.0.0 Beta (early access) from the n8n version dropdown and selects Save and restart. n8n's docs warn that major-version updates can't be rolled back, and n8n recommends the Stable track for mission-critical workloads. On Cloud, the safest move is to clear the Migration Report and wait for the stable 3.x release.
Rollback: plan it before you need it
n8n states plainly that moving to 3.x is one-way: there is no going back to 2.x afterwards. On a self-hosted instance, "rollback" therefore means restoring the backup you took, not starting the old image against the upgraded database.
docker compose down
docker run --rm -v n8n_data:/data -v ~/n8n-backup:/backup alpine \
sh -c "find /data -mindepth 1 -delete && tar xzf /backup/n8n_data-YYYY-MM-DD.tgz -C /data"
# Postgres only: start just the database, then restore the dump
docker compose up -d postgres
docker compose exec -T postgres pg_restore --clean -U n8n -d n8n < ~/n8n-backup/n8n-YYYY-MM-DD.dump
sed -i 's/^N8N_VERSION=.*/N8N_VERSION=2.45.5/' .env # the tag you wrote down
docker compose up -dAnything that happened after the upgrade, such as new executions or edits, is lost with a restore. That is the real argument for upgrading a test copy first, and for waiting for the stable release if your automations handle orders, leads or payments.
FAQ
When is the n8n 3.0 stable release?
n8n plans the stable 3.x release for early December 2026. The beta (3.0.0) came out on October 27, 2026, and 3.0.1 on October 28. n8n's release notes page is where the stable date will be confirmed.
Can I stay on n8n 2.x?
Yes, for a while. n8n says 2.x will keep receiving security and critical bug fixes for 12 months after the 3.x stable release, while new features ship only on 3.x. Keep updating to the latest 2.x patch in the meantime.
Does n8n 3.0 work with npm or npx?
No. Self-hosted n8n 3.0 requires a Docker-based deployment, and n8n 3.0 does not publish a runnable n8n package to npm. Move your existing instance to Docker on your current 2.x version first, then upgrade. Kubernetes and Helm setups are not affected.
Is the HTTP Request node removed in n8n 3.0?
No. Only the legacy HTTP Request Tool node is removed. The HTTP Request node stays, and you can still connect it to an AI Agent's Tool input.
What replaces the Function node in n8n 3.0?
The Code node. Use its Run Once for All Items mode in place of Function, and Run Once for Each Item in place of Function Item. The Migration Report lists every workflow that still uses them.
Can I downgrade from n8n 3.0 to 2.x?
Not in place. n8n says the move to 3.x is one-way. On a self-hosted instance you can only go back by restoring a full backup taken before the upgrade, and n8n Cloud does not allow rolling back a major-version update.
More n8n fixes: production webhook not working behind a proxy and Google OAuth tokens expiring every 7 days.
Rather not upgrade a live instance yourself? We'll do it.
Our n8n / Make Workflow Repair starts with a diagnosis within 24 hours on business days ($149, credited toward the repair), followed by a fixed written quote for the upgrade work. Fixed-price repairs start from $390, with 20% off for new customers. If old workflows need a rebuild on current nodes, Workflow Automation starts at $2,500.
Sources
- n8n Docs: v3.0 Breaking changes, checked October 28, 2026
- n8n Docs: v3.0 Migration tool (Migration Report)
- n8n Community: Announcing n8n version 3.0 (October 23, 2026) and staff replies
- n8n GitHub releases (n8n@3.0.0, October 27, 2026; n8n@3.0.1, October 28, 2026)
- n8n Community: Security update, October 28, 2026
- n8n Docs: Release notes
- n8n Docs: One-line setup
- n8n Docs: Install with Docker
- n8n Docs: Back up and restore
- n8n Docs: Update your n8n Cloud version