n8n 2.0 Migration Guide: Breaking Changes & Upgrade
Upgrade to n8n 2.0: breaking changes, database migration (MySQL to PostgreSQL), pre-flight checklist, and step-by-step troubleshooting for self-hosted instances.
n8n 2.0 launched Dec 15, 2025, and it's not backward-compatible. If you self-host n8n on 1.x, you need a plan before upgrading. This guide covers the breaking changes you'll hit, a step-by-step pre-flight checklist, how to migrate your database without losing workflows, and what to do when something breaks mid-upgrade.
What's n8n 2.0, and Why Should You Care?
n8n 2.0 is built on a security-first philosophy, with three pillars: security, reliability, and performance. It shipped Dec 15, 2025, after a beta period of one week. The team behind n8n (190+ people) redesigned core infrastructure to handle larger workflows faster. For you: better reliability, but mandatory upgrades and database changes.
n8n is built by a team of 190+ people and powers workflows for 115K+ community members. Version 2.0 represents a significant infrastructure redesign, not a minor patch. The n8n GitHub repo has 210.7K stars and 61.5K forks, reflecting the project's maturity and adoption. The release prioritizes security and performance, but that means breaking changes.
You cannot skip 2.0 forever. n8n 1.x will be supported for three months post-release (ending March 15, 2026), after which it no longer receives security updates. If you're on 1.x now, you're on borrowed time. The upgrade is not optional.
The good news: 2.0 is faster. It eliminates SQLite as a database option (replaced by PostgreSQL) and upgrades task runners to handle parallel execution better. If you've hit performance walls on 1.x, 2.0 likely fixes them. But first, understand what breaks when you upgrade n8n self-hosted instances.
The Breaking Changes That Matter Most for Self-Hosted
Self-hosted n8n 2.0 has six critical breaking changes: database migration (MySQL/MariaDB to PostgreSQL), environment variable access in Code nodes (now restricted), task runner defaults changed, file system access restricted to ~/.n8n-files, local file trigger and ExecuteCommand nodes disabled, and the Start node removed. Each requires action before or after upgrade.
n8n provides a Migration Report tool (built into 1.x) that scans your instance and flags which breaking changes affect you. Run it before upgrading. It's your most valuable pre-flight tool.
The breaking changes split into three tiers:
Tier 1: Blocking. You cannot upgrade until you fix these.
- Database migration: n8n 2.0 drops SQLite and MySQL/MariaDB support. PostgreSQL is mandatory. Your data doesn't move automatically; you run a migration tool.
- Start node removed: If you have workflows that begin with a Start node (manual trigger), 2.0 will not load them until you replace it with a Manual Trigger node.
Tier 2: Runtime errors. The upgrade succeeds, but workflows fail mid-execution.
- Code nodes losing environment variable access: n8n 2.0 restricts Code nodes from reading process.env. If your Code nodes reference $SLACK_API_KEY or similar, they fail until you either re-enable env access or move credentials to n8n's credential store.
- Local File Trigger disabled: If you have a workflow triggered by file system changes, it stops working (the node is disabled by default).
- ExecuteCommand node disabled: Running shell commands from workflows no longer works out-of-the-box.
Tier 3: Performance/security. Workflows run but behave differently.
- Task runners default to enabled: Parallel execution is now the default. Sequential workflows may hit race conditions if not designed for concurrency.
- File access restricted: Code nodes and other integrations can only read/write to ~/.n8n-files, not the entire filesystem.
Pre-Upgrade Checklist: 5 Steps Before You Start
Before upgrading, check your n8n version, back up your database, export your workflows, run the Migration Report, and document your encryption key. This checklist prevents data loss and identifies which breaking changes affect you. All five steps take under 30 minutes.
Step 1: Verify you're on a supported version. Check your n8n version: in the UI, go to Settings > About. If you're on 1.47 or later, you're eligible to upgrade. If you're on 1.40 or earlier, you must upgrade to 1.47 first (intermediate step). This takes ~10 minutes.
Step 2: Back up your database. If you're using MySQL/MariaDB (the most common self-hosted setup), export your entire n8n database:
mysqldump -u n8n_user -p n8n_db > n8n_backup_$(date +%Y%m%d).sql
For PostgreSQL users, use pg_dump instead:
pg_dump -U n8n_user -d n8n_db > n8n_backup_$(date +%Y%m%d).sql
Store the backup on a separate server or cloud storage. If the upgrade fails, you can restore from this backup and roll back to 1.x.
Step 3: Export your workflows. In n8n UI, navigate to Workflows. Select all workflows (or the critical ones). Use the bulk export feature (three-dot menu > Export). Save the JSON file to your local machine. This takes ~5 minutes but is essential if you need to rebuild manually. If you're new to self-hosted setups, review how to self-host n8n for context on your infrastructure.
Step 4: Run the Migration Report. n8n 1.47+ includes a built-in Migration Report. Access it via CLI:
n8n migrations:check
Or via the UI: Settings > Migration Report. The report lists every workflow and integration that will break in 2.0. Review it carefully. If you see "Start nodes found: 3", you know you have three workflows to fix before upgrading.
Step 5: Document your encryption key. Your workflows and credentials are encrypted at rest. If you've customized N8N_ENCRYPTION_KEY, document it now. If the upgrade fails and you need to restore from backup, you'll need this key to decrypt your data. Keep it in a password manager, not in a text file on your laptop.
Database Migration: MySQL/MariaDB to PostgreSQL (The Most Disruptive Change)
PostgreSQL is now mandatory; MySQL and MariaDB no longer work. If you're on MySQL/MariaDB, n8n 2.0 includes a built-in migration tool that exports your data and loads it into PostgreSQL. The process takes 10-30 minutes depending on data size and must complete before you can start the 2.0 instance.
This is the single biggest infrastructure change in 2.0. Here's why: MySQL and MariaDB have concurrency limits that break under heavy parallel task execution. PostgreSQL handles the new task runner architecture (enabled by default in 2.0) without bottlenecks. n8n is not dropping MySQL out of spite; they're dropping it because 2.0 simply requires PostgreSQL.
Before migration:
- Set up a fresh PostgreSQL instance (13 or later). If you're self-hosting on a VPS, install PostgreSQL on the same server or a dedicated database box. If you use a managed database service, create a new PostgreSQL database.
- Create a database user with full permissions:
CREATE USER n8n_user WITH PASSWORD 'your_secure_password';
CREATE DATABASE n8n_db OWNER n8n_user;
GRANT ALL PRIVILEGES ON DATABASE n8n_db TO n8n_user;
- Test the connection from your n8n server:
psql -h postgres-host -U n8n_user -d n8n_db
During migration: Run the migration tool in your 1.47 instance:
n8n migrations:run mysql-to-postgresql \
--from-host mysql-host \
--from-user n8n_user \
--from-password 'mysql_password' \
--from-db n8n_db \
--to-host postgres-host \
--to-user n8n_user \
--to-password 'postgres_password' \
--to-db n8n_db
The tool exports all workflows, credentials, and execution logs from MySQL to PostgreSQL. It does not modify your MySQL database, so you can re-run the command if it fails.
Common errors:
- "Connection refused on postgres-host:5432" - Check that PostgreSQL is listening on that IP. Run
ss -tlnp | grep 5432on the PostgreSQL server. - "User n8n_user does not have CREATEDB privilege" - The migration tool needs permission to create temporary tables. Grant it:
ALTER USER n8n_user CREATEDB; - "Migration interrupted: disk full" - The migration tool caches data to disk. Ensure your /tmp has at least 2GB free.
If migration fails halfway, check the migration log: tail -f /path/to/n8n/.pm2/logs/n8n.log. Do not start the 2.0 instance with an incomplete PostgreSQL database; roll back to your MySQL backup and restart 1.47. Then debug and re-run the migration.
Code Nodes & Environment Variables: Security Lockdown
n8n 2.0 blocks Code nodes from reading process.env by default. If your Code nodes reference $API_KEY or similar variables, they fail with "process is not defined" errors. You have two options: re-enable env access (less secure) or migrate credentials to n8n's credential store (recommended).
This change affects self-hosted instances most. In 1.x, Code nodes had full access to environment variables. This is a security risk: a malicious workflow (or a workflow you imported from an untrusted source) could exfiltrate your API keys. In 2.0, Code nodes run in a sandbox that blocks process.env access.
Option A: Migrate to n8n Credentials (Recommended)
Create a credential in n8n for each API key:
- Go to Credentials > Add New > Generic API Key.
- Enter your SLACK_API_KEY, GITHUB_TOKEN, etc.
- In your Code node, reference the credential:
const { slack_api_key } = $credentials.getAll();
This is safer and cleaner. Your keys are encrypted at rest in n8n's database, not visible to the Code node. If you export a workflow, the credentials are not included; the workflow re-links them when imported elsewhere.
Option B: Re-enable Environment Variable Access (Less Secure)
If you have dozens of Code nodes and migrating credentials is infeasible, you can re-enable env access:
N8N_BLOCK_ENV_ACCESS_IN_NODE=false
Add this to your.env file before starting 2.0, and Code nodes will regain access to process.env. The downside: you lose the security benefit of the sandbox, and any workflow can read all env variables. Use this only if you control all workflows and trust all integrations.
How to find which Code nodes are affected:
- Run the Migration Report (from Step 4 above). It flags workflows with Code nodes.
- For each flagged workflow, open it in edit mode and look for Code nodes that reference process.env.
- Search the code:
process.envwill not be found if the node has no env access.
Task Runners, File Access, Disabled Nodes: Security Defaults
n8n 2.0 enables task runners by default (parallel execution), restricts file access to ~/.n8n-files, and disables ExecuteCommand and Local File Trigger nodes. These changes improve security and stability but may break workflows that relied on sequential execution or file system access.
Task Runners: Parallelism by Default
In 1.x, workflows executed sequentially by default. In 2.0, task runners enable parallel execution. If you have 10 workflows queued, they run concurrently instead of one-at-a-time.
The benefit: Higher throughput, faster processing. The risk: Race conditions. If two workflows access the same external resource (e.g., writing to the same Google Sheet row simultaneously), they may corrupt data.
Action: After upgrading, review workflows that modify shared resources. Add locking or sequencing logic if needed. For 90% of use cases, parallelism is a win with no downside.
File Access: Restricted to ~/.n8n-files
Code nodes and file-based integrations can now only read/write inside ~/.n8n-files. If you have a workflow that processes files in /home/ubuntu/documents, it will fail in 2.0 unless you first copy files to ~/.n8n-files.
This is a security boundary. It prevents workflows from accidentally (or maliciously) reading sensitive files outside the n8n directory.
Action: If you have file operations, migrate them to ~/.n8n-files or use a cloud storage integration (Google Drive, S3) instead of local filesystem. The latter is more robust anyway.
Local File Trigger & ExecuteCommand: Disabled
Both nodes are disabled by default:
- Local File Trigger: Monitors filesystem for new files. Disabled because it conflicts with the file access restriction.
- ExecuteCommand: Runs shell commands (e.g.,
bash script.sh). Disabled because shell access is a security risk in a multi-tenant or exposed environment.
You can re-enable them in the config:
N8N_NODES_ENABLED=local-file-trigger,execute-command
But only do this if you control the workflow editor and trust all users. For public or multi-team instances, leave them disabled.
The New Publish/Save Model: Day-to-Day Changes
n8n 2.0 separates Save (preserves draft) from Publish (deploys to production). Save now preserves workflow state without executing listeners, while Publish activates the workflow. This prevents accidental deployments and enables rollback to previous versions.
In 1.x, the Save button meant "save and activate." You edited a workflow, hit Save, and it went live immediately. If you made a mistake, you had no way to rollback; you had to manually edit and re-save.
In 2.0, there are two buttons: Save and Publish.
Save = Draft mode. Your changes are stored but not live. Listeners (webhooks, scheduled triggers, manual triggers) do not execute. Use this when you're iterating on a workflow and not ready for production.
Publish = Production mode. Your workflow is now active and listeners fire. This is equivalent to the old Save behavior.
The workflow versioning is automatic. Every Publish creates a version snapshot. You can roll back to a previous Publish with one click. No more "I wish I had a backup of that workflow from last week."
How this changes your workflow:
Before 2.0: You edited a workflow, saved it, then ran tests to see if it worked. If it broke production, you had no easy rollback.
With 2.0: You edit, Save (draft), test via "Execute Workflow" button, then Publish when confident. If it breaks, you rollback to the previous version in seconds. Version history is visible under Workflow Settings > Versions.
For self-hosted teams, this means fewer incidents and faster recovery when something does go wrong.
Post-Upgrade Testing & Troubleshooting
After upgrading to 2.0, test critical workflows immediately: check Code nodes, file operations, OAuth integrations, and parallel execution. Common failures are "process is not defined" (Code node env access), "file not found" (file path restrictions), or "connection refused" (PostgreSQL). Rollback and debug if needed.
Testing Workflow (Checklist):
- Start the 2.0 instance and check the migration log:
tail -f /path/to/n8n/.pm2/logs/n8n.log
Look for "n8n started". If you see errors like "Cannot connect to PostgreSQL", the database migration failed. Stop here and rollback.
- Execute your critical workflows manually: In n8n UI, open each production workflow. Click the Execute button. Watch the execution log in real-time. Look for:
- Errors like "process is not defined" (Code node env access issue)
- "EACCES: permission denied" (file access restriction)
- "Integration failed" (credential mismatch)
- Test a webhook workflow:
If you have a workflow with a webhook trigger, POST data to the webhook endpoint. Replace
<instance-url>with your n8n instance URL and<webhook-path>with your webhook path:
curl -X POST https://<instance-url>/webhook/<webhook-path> \
-H "Content-Type: application/json" \
-d '{"test":"data"}'
Check if the workflow triggers and executes correctly.
- Monitor for race conditions: Queue multiple workflows simultaneously. If your database or integrations show corruption or unexpected behavior, you've hit a concurrency issue (task runner parallelism). Disable task runners or add locking logic.
Common Issues & Fixes:
| Issue | Cause | Fix |
|---|---|---|
| "Cannot connect to PostgreSQL" | Database migration incomplete or PostgreSQL not running | Check PostgreSQL is running: systemctl status postgresql. Verify connection: psql -h postgres-host -U n8n_user -d n8n_db |
| "process is not defined" | Code node accessing process.env | Re-enable env access: N8N_BLOCK_ENV_ACCESS_IN_NODE=false or migrate to n8n credentials |
| "File not found: /home/user/file.txt" | File outside ~/.n8n-files | Move file to ~/.n8n-files or use cloud storage integration |
| "Connection refused" | OAuth callback URL mismatch | Update OAuth app callback URL to match your 2.0 instance domain |
| "Start node: not supported" | Workflow has deprecated Start node | Replace Start node with Manual Trigger node and republish |
Rollback procedure (if needed):
If 2.0 is broken and you need to go back:
- Stop the 2.0 instance:
n8n stop - Restore your MySQL/MariaDB backup:
mysql -u n8n_user -p n8n_db < n8n_backup_YYYYMMDD.sql
- Restore your 1.47 codebase and start:
n8n start
- Workflows resume on 1.47. The PostgreSQL database is left untouched (you can re-attempt migration later).
Do not attempt to merge 2.0 data with 1.x data. Keep them separate until you're confident in 2.0.
Frequently Asked Questions
What are the breaking changes in n8n 2.0?
Six major ones: database migration (MySQL/MariaDB to PostgreSQL), Code node environment variable access restrictions, task runner parallelism by default, file system access limited to ~/.n8n-files, ExecuteCommand and Local File Trigger nodes disabled by default, and the Start node removed in favor of Manual Trigger nodes.
How do I migrate from n8n 1.x to 2.0?
Run the built-in migration tool in 1.47+: n8n migrations:run mysql-to-postgresql. This exports your workflows and credentials from MySQL to PostgreSQL. Then upgrade to 2.0, start the new instance, and test your workflows. Total time: 20-60 minutes depending on data size.
Can I upgrade directly without breaking my workflows?
Partially. The database migration is automatic via the tool. However, workflows with Code nodes accessing process.env, file system operations, or Start nodes will fail until you fix them. The Migration Report tells you which workflows need attention before you upgrade. Plan for 2-4 hours of testing and fixes after the upgrade.
What is the Publish/Save feature in n8n 2.0?
Save now preserves your workflow as a draft without activating it. Publish deploys the workflow to production. Every Publish creates a version snapshot, so you can rollback instantly if something breaks. This replaces the old "Save to activate" model.
What do I do if Code nodes fail after upgrading to 2.0?
Code nodes can no longer access process.env by default (security feature). Re-enable it temporarily: N8N_BLOCK_ENV_ACCESS_IN_NODE=false. Or migrate to n8n's credential store: create a Generic Credential and reference it in the Code node via $credentials.getAll(). The latter is more secure long-term.
How long does the n8n 2.0 upgrade take?
Database migration: 10-30 minutes. Testing and fixing broken workflows: 1-4 hours depending on how many Code nodes and file operations you have. Plan a maintenance window of 2-6 hours for a production instance.
Can I roll back from n8n 2.0 to 1.x if something breaks?
Yes. Keep a backup of your 1.47 MySQL database before migration. If 2.0 fails, stop the instance, restore from your MySQL backup, and restart 1.47. Your workflows resume immediately. Do not keep both 2.0 PostgreSQL and 1.x MySQL running simultaneously; they can get out of sync.
The Bottom Line
n8n 2.0 is mandatory by March 2026 (end of 1.x support). The upgrade is not trivial: database migration is mandatory, Code nodes need auditing, and file access changes. But the work is straightforward if you follow the pre-flight checklist. Plan a 2-6 hour maintenance window, run the Migration Report first, and test critical workflows before you go live.
If managing infrastructure distracts you from building workflows, Opsily's managed n8n hosting handles upgrades, backups, and infrastructure for you. No maintenance windows. No rollback risks. You focus on automation, we handle the ops.