n8n 3.0 breaking changes: how to prepare and upgrade safely

n8n 3.0 is not a feature release. n8n describes it as a release focused on reliability, stability and security, with new features shipping later on 3.x. What it does bring is a long list of breaking changes: legacy nodes are removed, self-hosted installs must run on Docker, several environment-variable defaults change, and a few behaviours shift in ways that can silently change workflow output.

Who is affected

Everyone — self-hosted Community, Cloud and Enterprise/Business — is affected by the removed nodes and behaviour changes. Self-hosted instances are additionally affected by the deployment and environment-variable changes. Two rules matter before anything else:

• The upgrade is one-way. There is no rollback from 3.x to 2.x; the only way back is restoring a backup.
• There is no direct jump from 1.x to 3.x. Instances on 1.x must move to 2.x first (1.x support ends December 31, 2026).

Step 1: Run the Migration Report

n8n ships a built-in checker. Update to the latest 2.x release (the report needs at least 2.39), then open Settings > Migration Report. It has two tabs — Workflow issues and Instance issues — and you should work through both.

The report lists affected workflows and settings, can apply automatic fixes for many issues (each fix is saved as a new workflow version for you to review and publish, while the published version keeps running on 2.x), suggests an owner for each workflow, lets you mark unused or long-idle workflows as “won't fix”, and exports a CSV summary for planning.

Removed nodes and their replacements

Workflows that still use removed nodes will fail on 3.0, and published workflows with removed trigger nodes stop firing. The most common ones in real-world instances:

Some removals have no direct replacement: LangChain Code, Motorhead and Zep memory, Zep Vector Store, SerpApi and Orbit. Plan a redesign for workflows that depend on them. AI Transform nodes can no longer be added or run; the Migration Report can convert existing ones to Code nodes that keep the generated JavaScript, but nodes that never generated code must be rebuilt by hand. The $getPairedItem helper is also gone — use $('Node name').item, .itemMatching() or .pairedItem() instead.

Self-hosted: Docker is now required

n8n 3.0 no longer supports installs run with npm or npx n8n. If you self-host that way, move to Docker (n8n's one-line setup or Docker Compose) before upgrading. Existing Docker Compose setups need no change, and Kubernetes/Helm installs are not affected.

Check these environment-variable changes before the first 3.0 start:

• Storage folder rename: ~/.n8n/binaryData becomes ~/.n8n/storage on first start, and n8n won't start if both folders exist. Mount the new path, or set N8N_STORAGE_PATH to the old one.
• N8N_DEFAULT_BINARY_DATA_MODE=default is no longer valid — set filesystem, s3, azure or database explicitly.
• Unverified community nodes stop loading: N8N_UNVERIFIED_PACKAGES_ENABLED now defaults to false.
• Code tasks time out sooner: N8N_RUNNERS_TASK_TIMEOUT drops from 300 to 60 seconds. Set it explicitly if you run long Code steps.
• Queue mode: OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS is removed — manual executions always run on workers, so size worker memory accordingly.
• Compression limits shrink: max decompressed size goes from 2 GiB to 256 MiB and max zip entries from 5,000 to 1,000.
• Renamed/removed variables: use DB_PING_TIMEOUT_MS instead of N8N_DB_PING_TIMEOUT; N8N_WORKFLOW_TAGS_DISABLED and N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION are gone.

Behaviour changes that won't throw an error

These are the dangerous ones, because the workflow keeps running but the output changes:

• Always Output Data on If/Switch: an empty item is now added only when every output is empty, not once per empty branch.
• Gmail Trigger (v1–1.3) now behaves like v1.4: “Max Emails per Poll” applies to every poll, drafts are skipped unless “Include Drafts” is on, and sent/scheduled emails no longer trigger.
• Edit Image v1/1.1 are replaced by v2, which uses a different library — re-test text placement, resizing and quality settings.
• Chat Trigger WebSocket frames (Using Response Nodes mode) are now JSON objects with a type field; custom chat clients must parse JSON, and @n8n/chat needs 1.31.0 or later.

Security changes to plan for

• Slack: the Slack API credential now requires a signing secret. Slack Trigger workflows stop receiving events until you add it (Slack app → Basic Information → Signing Secret) and re-publish.
• Encryption key rotation is on by default, managed under Settings > Data Encryption Keys. Back up before upgrading.
• SSRF protection blocks more IP ranges by default when enabled. If a workflow calls an internal service, allow it with N8N_SSRF_ALLOWED_IP_RANGES or N8N_SSRF_ALLOWED_HOSTNAMES.
• Chat Hub is off by default; keep it through 3.x by adding chat-hub to N8N_ENABLED_MODULES. n8n says it will be removed in 4.0.

A safe upgrade plan

1. Update to the latest 2.x and open the Migration Report.
2. Triage every item in both tabs: apply automatic fixes, review the new versions, replace removed nodes, and mark dead workflows “won't fix”.
3. Self-hosted on npm/npx? Move to Docker first, on 2.x, and confirm everything still runs.
4. Set environment variables you need to keep current behaviour (timeouts, unverified packages, compression limits, Chat Hub, storage path) and add Slack signing secrets.
5. Take a full backup of the database, encryption key and storage folder — this is your only rollback.
6. Upgrade a staging copy first, run your critical workflows end to end, then schedule the production upgrade. Expect only a short restart.

Credentials and execution history carry over. For most teams the real work is in step 2: auditing workflows built years ago on Function, Cron or Item Lists nodes, and re-testing the ones whose behaviour changes without an error. If you'd rather hand that off, an n8n expert can run the Migration Report audit and the upgrade for you, and an n8n VA can take over ongoing n8n maintenance afterwards.

Should you upgrade now or wait?

For production systems, waiting for the stable release in December is reasonable — 2.x stays supported with security fixes for 12 months after that. But don't wait to prepare: the Migration Report works today on 2.39+, and clearing it now turns the eventual upgrade into a routine restart instead of an emergency.

Frequently asked questions

Sources

• n8n docs: v3.0 breaking changes
• n8n blog: Introducing n8n 3.0
• n8n support: How do I prepare for n8n 3.0?
• n8n docs: Release notes