n8n 3.0 Drops This Month — Your npm Install Dies and 5 More Breaking Changes for Self-Hosters

n8n 3.0 is expected in October 2026, according to the official 3.0 breaking-changes page — it is not released yet; the newest version as of October 20, 2026 is the 2.45.0 pre-release (GitHub releases). If you self host n8n on your own hardware — a mini-PC, a NAS, a Pi in the cupboard — this release decides how you'll run it: npm and npx installs stop being supported; self-hosted n8n goes Docker-only. Legacy nodes and helpers are removed, and several defaults change in ways that break workflows silently.

This n8n upgrade guide covers the n8n 3.0 breaking changes the VPS-centric write-ups skip: find what breaks on your instance, move off npm with a docs-verified n8n docker install migration, and fix every removal before n8n 3.0 lands.

⚠️ Honest testing note. We did not run this migration live — n8n 3.0 isn't out, so nobody outside n8n has. Every step is verified against the official 2.x docs and the published 3.0 breaking-changes page; anything that could change before release is labeled. Verify on staging first.

Step 0: Let Your 2.x Instance Tell You What Will Break

Open Settings › Migration Report — n8n ships it for exactly this transition. It lists the workflows, nodes, and settings on your installation that n8n 3.0 will break. Keep it open and work through it below. Also scan your startup logs once: 2.x logs a deprecation warning for every config change affecting your instance. And confirm your install method — which n8n under your npm global prefix means you're one of the installs 3.0 leaves behind.

The Big One: npm and npx Installs Are Done — Docker Only

The official line is blunt: "Self-hosted n8n requires a Docker-based deployment. n8n 3.0 no longer supports installations run using npm or npx n8n, and n8n 3.0 doesn't publish a runnable n8n package to npm." Your npm install won't be switched off remotely — but it will never see 3.0 or another security patch. This is the n8n npm deprecated endgame: migrate to Docker on 2.x, then upgrade.

Step 1 — Back up the npm install

Export workflows and credentials while the old install runs, then copy the data directory — the SQLite DB and encryption key live in ~/.n8n. Note encryptionKey in ~/.n8n/config for the compose file.

mkdir -p ~/n8n-migration-backup && cd ~/n8n-migration-backup n8n export:workflow --all --output=./workflows/ n8n export:credentials --all --output=./credentials/ cp -r ~/.n8n ./n8n-data-backup

Step 2 — Write the compose file (homelab edition)

Migrate onto the latest 2.x first — not straight to 3.0. Pin an explicit version tag: the latest→stable and next→beta renames mean an unpinned stable tag jumps to 3.0 on release day. This n8n docker compose setup carries your old data dir into the container — pull the official n8nio/n8n image on Docker Hub only; for the Traefik/TLS reference layout, see the official Docker Compose guide.

mkdir -p ~/n8n-docker && cd ~/n8n-docker cp -r ~/.n8n ./n8n-data   # config, DB, and encryption key travel together # sudo chown -R 1000:1000 ./n8n-data   # if the container user can't write to it

services:   n8n:     # Migrate on the newest 2.x FIRST. Take the 3.x tag only after this is stable.     image: n8nio/n8n:2.45.0     restart: unless-stopped     ports:       - "127.0.0.1:5678:5678"   # localhost only — the proxy is the front door     environment:       - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true       - N8N_ENCRYPTION_KEY=paste-your-key-here   # SAME key as the npm install       - N8N_HOST=n8n.example.com       - N8N_PORT=5678       - N8N_PROTOCOL=https       - N8N_WEBHOOK_URL=https://n8n.example.com/       - NODE_ENV=production       - GENERIC_TIMEZONE=Asia/Karachi       - TZ=Asia/Karachi     volumes:       - ./n8n-data:/home/node/.n8n

Step 3 — The volume gotcha that stops n8n 3.0 from starting

n8n 3.0 renames ~/.n8n/binaryData to ~/.n8n/storage on first start — and refuses to start if both directories exist. If both are in your copied data dir, move binaryData's contents into storage and delete binaryData. The old in-memory binary data mode (N8N_DEFAULT_BINARY_DATA_MODE=default) is gone too — set filesystem, s3, azure, or database.

Step 4 — Put it behind your homelab reverse proxy

Proxy to the container on 5678, keep N8N_WEBHOOK_URL on your public HTTPS URL (webhooks break silently without it), and set GENERIC_TIMEZONE to your timezone for Schedule Trigger nodes. 502s through the proxy while n8n answers on localhost:5678 means the proxy-to-container path is at fault — our Nginx 502 Bad Gateway in Docker fix guide covers that exact failure.

Step 5 — Start, import, verify — then take the 3.0 tag

docker compose up -d docker compose logs -f n8n   # watch for startup deprecation warnings

Confirm workflows and credentials survived, re-run the Migration Report, and let it bake a few days. Then change the tag to the n8n 3.0 release, docker compose pull && docker compose up -d, and read the startup logs. The Pi-hole v6.5 safe-update workflow covers that pull-and-recreate rhythm in detail.

Removed Nodes and Helpers: Symptom → Fix for Each

n8n 3.0 removes older nodes, modes, and helpers that newer patterns replaced. The rule is blunt: workflows that use a removed node fail. The Migration Report lists every affected workflow — here is the documented fix for each, to apply before n8n 3.0 arrives.

Legacy code nodes → Code node

Symptom: workflows on the old Function, Function Item, or Item Lists nodes fail. Fix: move Function/Function Item to the Code node — Run Once for All Items for Function, Run Once for Each Item for Function Item — and re-test each script in the stricter task-runner sandbox. Replace Item Lists with the node matching its operation: Split Out, Aggregate, Sort, Limit, Remove Duplicates, or Summarize.

Cron and Interval → Schedule Trigger

Symptom: scheduled workflows on the old Cron or Interval nodes fail. Fix: replace both with the Schedule Trigger node — and double-check GENERIC_TIMEZONE, or midnight schedules shift hours when the container timezone doesn't match the host.

Expressions and sub-workflows

Symptom: expressions calling $getPairedItem() fail at runtime; sub-workflow calls using the Local File or URL source fail. Fix: rewrite $getPairedItem() with item linking — $('<node-name>').item, .itemMatching(<index>), or .pairedItem(<index>). Replace the removed sub-workflow sources with Database (import the sub-workflow first) or Define Below. $evaluateExpression() is also gone from the Code node — evaluate in a node field first, e.g. an Edit Fields node before the Code node.

AI nodes → Tools Agent and current nodes

Symptom: workflows on AI Agent version 1 modes (SQL, Conversational, OpenAI Functions, Plan and Execute, ReAct) fail, as do the legacy OpenAI, OpenAI Assistant, OpenAI Model, legacy HTTP Request Tool, Manual Chat Trigger, Chat Messages Retriever, LangChain Code, Motorhead/Zep memory nodes, and old vector-store pairs. Fix: update AI Agent nodes to the latest version — Tools Agent replaces all removed modes. For SQL Agent cases, pair a Postgres/MySQL tool sub-node with a recent AI Agent node. No replacement exists for LangChain Code (use the Code node), SerpApi (HTTP Request to its REST API), or Orbit (service shut down).

The rest — quick swap list

• HTML Extract → HTML node's Extract HTML Content; iCalendar → Convert to File's Convert to ICS; Convert to/from binary data → Convert/Extract from File; Read/Write Binary File(s) → Read/Write Files from Disk; Read PDF → Extract From PDF; Workflow Trigger → n8n Trigger.
• Chat Hub → off by default in n8n 3.0, removed in 4.0. Sessions stay in the DB; add chat-hub to N8N_ENABLED_MODULES to keep it through 3.x.
• Editor "Import from URL" → copy-paste, Import from File, CLI, or API. Ask AI tab in the Code node → write code directly (generated code keeps running).

✅ Good news: the AI Transform node auto-migrates to a Code node on upgrade, keeping the same JavaScript — existing workflows keep working. You just can't add new ones after n8n 3.0.

Silent Breakage: Behavior and Security Changes

These remove nothing — but running workflows can change results or fail with confusing errors. On a home server nobody watches daily, these are the ones that bite at 3 AM after the n8n 3.0 upgrade.

Code node timeout cut from 300s to 60s

Symptom: Code node tasks running longer than a minute fail. Fix: the N8N_RUNNERS_TASK_TIMEOUT default drops from 300 to 60. Set it explicitly in your compose file if your tasks need more than a minute.

Unverified community nodes stop loading

Symptom: npm-installed community nodes vanish from the palette. Fix: the N8N_UNVERIFIED_PACKAGES_ENABLED default flips to false. Set it to true to keep your set, or move to verified community nodes.

Smaller behavior changes — quick hits

• Slack Trigger 401s: 3.0 requires a signing secret on the Slack API credential — add it before upgrading (from your Slack app's Basic Information page), then publish the workflow again. Until then, the workflow fails to publish and the trigger answers 401.
• Gmail Trigger < 1.4 runs as 1.4: drafts are skipped unless you enable Include Drafts, Max Emails per Poll applies to every poll (default 10, max 50), and sent/scheduled emails no longer trigger the workflow. Review each one in the Migration Report.
• Always Output Data on If/Switch: an empty item is added only when every output is empty now. Re-check affected nodes in the Migration Report.
• Compression limits drop: max decompressed size 2 GiB → 256 MiB, max zip entries 5,000 → 1,000. Set N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES=2147483648 and N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES=5000 to keep the old limits.
• Key rotation on by default: pre-upgrade credentials stay readable. Nothing to do — but one more reason the backup is non-negotiable.
• Bigger SSRF block list: four more ranges join default. Allowlist what you need via N8N_SSRF_ALLOWED_IP_RANGES / N8N_SSRF_ALLOWED_HOSTNAMES.
• Removed variables: N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION, N8N_DB_PING_TIMEOUT (→ DB_PING_TIMEOUT_MS), OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS (manual runs always use workers in queue mode — review worker memory).

Skipped the 2.x upgrades? These hit you too

Per the official 2.0 breaking-changes page, n8n 3.0 assumes changes many npm-install homelabs never applied: $env blocked in Code nodes, Execute Command/Local File Trigger disabled unless you clear NODES_EXCLUDE, Python in the Code node only via the external n8nio/runners image, workflows "published" not "activated", MySQL/MariaDB dropped. Apply these on 2.x during the Docker migration.

The Safe Upgrade Order (Homelab Discipline)

1. On 2.x, npm: Migration Report, export workflows and credentials, copy ~/.n8n, note the encryption key.
2. Migrate to Docker on 2.45.0 — pinned tag, same key, binaryData/storage check — verify behind the proxy, let it bake.
3. Work the Migration Report list: replace removed nodes, rewrite $getPairedItem(), add the Slack signing secret, set the variables you need, clean up removed env vars.
4. Then take the 3.x tag: docker compose pull && docker compose up -d, read the startup logs.

Apply the staging-first rule from our Mastodon 5.0 beta upgrade guide: clone the Docker setup to a second compose project, upgrade the clone, and exercise critical workflows there first. n8n 3.0 is the kind of upgrade where a breakage caught at 3 PM beats one discovered at 3 AM.

Frequently Asked Questions

Has n8n 3.0 been released yet?

No. As of October 20, 2026, the latest version is the 2.45.0 pre-release, and n8n 3.0 is expected in October 2026 per the official docs. The breaking-changes list is already published, so run the Migration Report and prepare now.

Will my npm install keep working after 3.0?

It keeps running, but 3.0 publishes no runnable npm package, so it never gets 3.0 or later security fixes. Migrate to the official Docker image on 2.x first, then upgrade.

Which nodes does n8n 3.0 remove?

Legacy Function, Function Item, Item Lists, LangChain Code, Cron, Interval, HTML Extract, iCalendar, binary read/write nodes, Read PDF, Workflow Trigger, Orbit, legacy OpenAI nodes, Manual Chat Trigger, Chat Messages Retriever, Motorhead/Zep memory nodes, and old vector-store pairs — plus Execute Sub-workflow's Local File/URL sources, AI Agent v1 modes, and $getPairedItem. Check Settings > Migration Report on 2.x first.

Why do long Code node scripts fail after upgrading?

The task-runner timeout default (N8N_RUNNERS_TASK_TIMEOUT) drops from 300 to 60 seconds in n8n 3.0. Set it explicitly in your compose file if your tasks need more than a minute.

Will my community nodes still load?

Only verified ones by default: 3.0 turns N8N_UNVERIFIED_PACKAGES_ENABLED off, so unverified npm community nodes stop loading. Set it to true, or switch to verified community nodes.

Why does n8n 3.0 refuse to start with a binaryData error?

On first start, 3.0 renames ~/.n8n/binaryData to ~/.n8n/storage and stops if both exist. Move binaryData's contents into storage, delete binaryData, and start again.

Running n8n or anything else in Docker on PHP? The php2shell RCE (CVE-2026-109618/19) is a patch-tonight emergency for every PHP container — our php2shell Docker patch guide walks the pull-and-recreate update.