Skip to content
zarif/automatesStart here
Research guideUpdated · Zarif

n8n 3.0 Upgrade Checklist for Self-Hosted n8n

Upgrading self-hosted n8n to 3.0: run the Migration Report, back up, move to Docker, replace removed nodes and check the changed env defaults.

An envelope passes through three connected blue workflow modules and emerges as a record card, with a separate review tray.

To upgrade self-hosted n8n to 3.0, open Settings > Migration Report first. It lists the workflows and instance settings on your own instance that need attention, and if the option is missing, update to n8n 2.39 or later. Fix what it lists while you're still on 2.x, then take a full backup, because there's no direct rollback from 3.x to 2.x. The storage folder, the removed variables and the changed defaults are changes you make when you switch to 3.0, not before. The 3.0 beta came out on October 27, 2026, and stable is planned for early December 2026.

Last checked November 20, 2026. There's a free printable version of this checklist on one page, with no sign-up.

This guide restates what n8n has published: the 3.0 breaking-changes page in its docs and the support article How do I prepare for n8n 3.0?. n8n's Introducing n8n 3.0 post announces the beta, says stable follows in early December, and describes the Migration Report as the place that lists which workflows and settings need updates. Nothing here was tested on a live upgrade. n8n calls 3.0.0 an early access release, so read the breaking-changes page again before you upgrade. Where this page and n8n disagree, follow n8n.

The dates that matter

MilestoneDate
n8n 3.0 betaOctober 27, 2026
n8n 3.0 stableEarly December 2026 (planned)
Support for n8n 1.x endsDecember 31, 2026
Security and critical fixes for n8n 2.x12 months after 3.0 is stable

If you still run 1.x, you have until the end of this year, and 1.x has to move to 2.x before it can go to 3.0 anyway. Going to 2.39 or later gets you off 1.x and gives you the Migration Report.

If you're on 2.x, nothing forces you onto 3.0 the week it ships. 2.x keeps getting security and critical fixes for 12 months after 3.0 is stable, so you can work through the list below on your own schedule.

Before you upgrade (on 2.x)

Steps 1 to 5 happen on the version you run today. None of them needs 3.0, and each one leaves 2.x working. Step 6 is a rehearsal: you upgrade the staging copy to 3.0 while production stays on 2.x.

1. Run the Migration Report

The Migration Report is n8n's list of what on your instance needs attention before 3.0. Open Settings > Migration Report. If you don't see it, update to n8n 2.39 or later first. If you're on 1.x, that means moving to 2.x, which you have to do before 3.0 anyway.

The report has two tabs, Workflow issues and Instance issues. Review both and save what they show. Fix the workflows it lists on 2.x, starting with the removed nodes in step 2.

2. Replace the removed nodes

These nodes are removed in 3.0. A workflow that uses one fails when it runs, and a published workflow that uses one doesn't activate when 3.0 starts.

Removed nodeUse instead
FunctionCode node, Run Once for All Items
Function ItemCode node, Run Once for Each Item
Item ListsSplit Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize
CronSchedule Trigger
IntervalSchedule Trigger
Read Binary File, Read Binary Files, Write Binary FileRead/Write Files from Disk
Read PDFExtract from File
Workflow Triggern8n Trigger
HTTP Request Tool (legacy)HTTP Request node on the AI Agent's Tool input
AI Agent node v1 and its older modesTools Agent

Rebuild one workflow at a time and run it against the same input before and after. A trigger that never fires is easy to miss, so check each rebuilt schedule's next run.

3. Move npm or npx installs to Docker

Self-hosted n8n 3.0 requires Docker. 3.0 no longer supports npm or npx installs, and n8n doesn't publish a runnable n8n package to npm for it. If you already run n8n with Docker Compose, you don't need to switch anything.

If you start n8n with npx n8n or a global npm install, move to Docker on the version you run today, check that everything works, and only then upgrade. Changing the install method and the major version at the same time leaves you two suspects when something breaks.

4. Add the Slack signing secret to Slack Trigger workflows

3.0 requires a signing secret on the Slack API credential. Workflows with a Slack Trigger node need it before you upgrade. Without it they fail to publish or stop receiving events.

Every other Slack workflow can wait. Step 9 covers those.

5. Take a full backup

There's no direct rollback from 3.x to 2.x. If the upgrade goes wrong, the way back is the backup you took before it.

Take the full backup after steps 1 to 4, so it holds the fixed workflows. Restore it onto a staging copy and open a few workflows. A backup you've never restored is a guess.

6. Rehearse the 3.0 upgrade on staging

Upgrade the staging copy from step 5 to 3.0, making the changes in steps 7 to 9 as you do. Production stays on 2.x. Run the workflows the Migration Report flagged and confirm the triggers fire. What breaks on staging is your list for production.

When you switch to 3.0

Steps 7 to 9 are 3.0 changes, so make them in the same step that moves an instance to 3.0: on staging in the step 6 rehearsal, then on production in step 10. Don't repoint the storage volume early, because 2.x still uses binaryData.

7. Point your volume at the storage folder

On first start, 3.0 renames ~/.n8n/binaryData to ~/.n8n/storage. If both folders exist, n8n stops with an error, so don't create a storage folder yourself.

If you mount a volume at binaryData, leave it there while you're on 2.x. When you switch to 3.0, mount it at storage instead or set N8N_STORAGE_PATH. If you set N8N_DEFAULT_BINARY_DATA_MODE=default, that value is no longer valid in 3.0, and n8n switches to filesystem.

8. Update your environment variables

Four variables are removed. Delete them from your .env or Compose file:

  • OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS
  • N8N_DB_PING_TIMEOUT. Use DB_PING_TIMEOUT_MS instead.
  • N8N_WORKFLOW_TAGS_DISABLED
  • N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION

Two defaults change. Set them only if you want the 2.x behavior:

  • N8N_UNVERIFIED_PACKAGES_ENABLED changes from true to false, so unverified community nodes stop loading. Set it to true to keep them.
  • N8N_RUNNERS_TASK_TIMEOUT drops from 300 (5 minutes) to 60 (1 minute). Set it explicitly if your tasks need longer than a minute.

9. Check Chat Hub, other Slack workflows, Import from URL and the Compression node

Four smaller changes can still surprise a team:

  • Chat Hub is off by default. If you use it, add chat-hub to N8N_ENABLED_MODULES.
  • Slack workflows without a Slack Trigger node: add the signing secret to the Slack API credential the next time you edit it.
  • Import from URL is removed from the editor. If your team shares workflows by link, agree on another route before the upgrade.
  • The Compression node's defaults drop to 256 MiB decompressed and 1,000 zip entries. A workflow that unpacks larger archives needs a look.

10. Upgrade production

Once staging runs cleanly, upgrade production with the same changes from steps 7 to 9. Keep the pre-upgrade backup until production has run cleanly for a while.

The printable checklist has every step on one page, with boxes to tick.

If n8n is new to you and you're still choosing between tools, the n8n vs Zapier cost comparison covers what self-hosting costs in time and money.

Frequently asked questions

When is n8n 3.0 released?

The 3.0 beta came out on October 27, 2026. Stable is planned for early December 2026, per n8n's support FAQ. Treat that as a plan, not a date, and check n8n's announcements before you schedule the upgrade.

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

Not directly. n8n says there's no direct rollback from 3.x to 2.x, so the way back is restoring the full backup you took before upgrading. Take it first, and test the upgrade on staging before production.

Can I still install n8n 3.0 with npm or npx?

No. Self-hosted n8n 3.0 requires Docker and doesn't support npm or npx installs. If you run n8n through npm or npx today, move to Docker on your current version first, then upgrade. Docker Compose users don't need to switch.

What replaces the Function, Cron and Item Lists nodes in n8n 3.0?

Function becomes the Code node in Run Once for All Items mode, and Function Item becomes the Code node in Run Once for Each Item mode. Cron and Interval become the Schedule Trigger node. Item Lists becomes Split Out, Aggregate, Sort, Limit, Remove Duplicates or Summarize, depending on the operation you used.

Do I have to upgrade to n8n 3.0 right away?

No. After 3.0 is stable, n8n gives 2.x security and critical fixes for 12 months. Support for 1.x ends on December 31, 2026, and 1.x has to move to 2.x before 3.0, so if you're on 1.x, move to 2.39 or later before then.

END OF ARTICLE

Not sure what to read next? Start here →