self hosting
N8N Upgrade Guide
Update self-hosted n8n regularly, check release notes for breaking changes, and test important upgrades in a separate environment before touching production.
Match your incident first
Start with the symptom you can prove
Container restarts after upgrade or compose pull
First check: Run docker compose ps and inspect the last 100 n8n log lines.
Wrong fix to avoid: Do not delete volumes to make the container start.
Verify: Container stays healthy and existing workflows/credentials remain visible.
Workflows disappear after recreating container
First check: Check compose volumes and whether /home/node/.n8n is persisted.
Wrong fix to avoid: Do not create new workflows until you confirm whether old data exists in a volume or backup.
Verify: A restart preserves workflows, credentials, executions, and settings.
Production URL is wrong in Docker deployment
First check: Inspect only the public URL-related env vars and the proxy route.
Wrong fix to avoid: Do not expose the container directly on the public internet to bypass proxy config.
Verify: Webhook URLs in the editor use the intended HTTPS domain.
- Use when
- self-hosted, upgrades
- First check
- Back up the active database and n8n data directory.
- Time to check
- 5-10 minutes
- Next step
- Run the recommended steps, then verify a production execution.
Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.
Quick Answer
Update self-hosted n8n regularly, check release notes for breaking changes, and test important upgrades in a separate environment before touching production.
Version awareness
Last reviewed 2026-05-21
Key Facts
- Update cadence
- n8n recommends updating frequently, around at least monthly.
- Risk reduction
- Frequent updates avoid large version jumps.
- Pre-check
- Check release notes for breaking changes.
- Testing
- Use a test environment before updating production when possible.
Production Diagnostic Matrix
Turn checks into a brief| Exact symptom or log | Likely cause | First check | Wrong fix to avoid | Verification |
|---|---|---|---|---|
| Container restarts after upgrade or compose pull | Missing required env var, incompatible database migration, or invalid compose service config. | Run docker compose ps and inspect the last 100 n8n log lines. | Do not delete volumes to make the container start. | Container stays healthy and existing workflows/credentials remain visible. |
| Workflows disappear after recreating container | n8n data was stored inside the container instead of a persistent volume or external database. | Check compose volumes and whether /home/node/.n8n is persisted. | Do not create new workflows until you confirm whether old data exists in a volume or backup. | A restart preserves workflows, credentials, executions, and settings. |
| Production URL is wrong in Docker deployment | WEBHOOK_URL, N8N_HOST, N8N_PROTOCOL, or reverse proxy labels are missing or inconsistent. | Inspect only the public URL-related env vars and the proxy route. | Do not expose the container directly on the public internet to bypass proxy config. | Webhook URLs in the editor use the intended HTTPS domain. |
| Database or volume permission errors after moving hosts | File ownership, mounted path, or Postgres credentials changed during migration. | Check volume mount paths, container UID expectations, and database auth logs. | Do not chmod everything recursively without a backup. | n8n starts and can read previous workflows after one restart. |
| Backup exists but restore does not work | Backup missed the database, .n8n folder, encryption key, or binary data storage. | Verify restore in a disposable environment before touching production. | Do not assume a SQL dump alone is enough when binary data or SQLite is used. | A restored test instance can open workflows, decrypt credentials, and run a smoke test. |
| Upgrade breaks a previously working workflow | Node behavior, credential schema, API response shape, or custom node compatibility changed. | Compare failing execution before/after upgrade and check release notes for affected nodes. | Do not immediately downgrade without checking database migration and rollback safety. | Smoke tests for triggers, credentials, expressions, and outbound calls pass on the target version. |
Recommended Steps
- Back up the active database and n8n data directory.
- Read release notes between your current version and target version.
- Test the update in a separate environment.
- Update using the method that matches your installation, such as Docker or npm.
- Run critical workflows after the update and monitor logs.
Verification
- The instance starts on the target version.
- Critical workflows activate and execute.
- No breaking-change symptoms appear in logs or user workflows.
First Commands / Checks
docker compose psdocker compose logs n8n --tail=100docker compose exec n8n printenv WEBHOOK_URL N8N_HOST N8N_PROTOCOL N8N_EDITOR_BASE_URLSafe Copyable Config
# Backup Postgres in a private shell
docker compose exec postgres pg_dump -U n8n_app n8n > backup-n8n.sql
# Record non-secret runtime facts
docker compose ps > backup-services.txt
docker compose exec n8n printenv WEBHOOK_URL DB_TYPE N8N_BINARY_DATA_MODE > backup-runtime-public.txt
# Restore only into a disposable test environment first
psql "postgresql://n8n_app:REDACTED@postgres:5432/n8n_restore" < backup-n8n.sqlN8N_HOST=automation.example.com
N8N_PROTOCOL=https
WEBHOOK_URL=https://automation.example.com/
GENERIC_TIMEZONE=UTC
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n_app
DB_POSTGRESDB_PASSWORD=REDACTED_CHANGE_ME
N8N_ENCRYPTION_KEY=REDACTED_GENERATE_ONCEWarnings
- Skipping many versions at once increases upgrade risk.
- Do not update production without a rollback path and current backup.