self hosting

N8N Backup and Restore Guide

Back up the active database, n8n user data, encryption key, and any external binary storage before upgrades or infrastructure changes.

Match your incident first

Start with the symptom you can prove

Jump to checks

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, backups
First check: Identify whether the instance uses SQLite or Postgres.
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

Back up the active database, n8n user data, encryption key, and any external binary storage before upgrades or infrastructure changes.

Version awareness

Last reviewed 2026-05-21

Applies to: self-hosted n8n, Docker Compose, Postgres, reverse proxy, backup/restore
Official docs checked: n8n Supported Databases, Update self-hosted n8n, n8n Docker Installation
Version-sensitive assumptions: n8n node parameters, credential names, and queue mode defaults can change between releases; confirm against your installed version before changing production.
What may change after upgrades: Node parameter names, credential scopes, webhook behavior, Docker image defaults, and queue worker expectations may shift after n8n upgrades.

Key Facts

Database data: Workflows, credentials metadata, executions, and settings depend on the active database.
SQLite path: The default SQLite file is under ~/.n8n/database.sqlite.
User data: The n8n user data directory also matters for Docker persistence and community nodes.
Encryption key: The encryption key must be preserved to keep encrypted credentials usable.

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

Identify whether the instance uses SQLite or Postgres.
Back up the active database.
Back up the n8n user data directory and community node directory.
Store the encryption key securely with the deployment secrets.
Test restore in a separate environment before relying on the backup.

Verification

A restored test instance can start.
Workflows are visible after restore.
Credentials can be used after restore.
Community nodes load if workflows depend on them.

First Commands / Checks

Check container state Use first when n8n is down, restarting, or behaving differently after a deploy.

docker compose ps

Secrets note: This lists service names and status only; it should not print credential values.
Verification: n8n, database, Redis, and worker services are running or the failing service is obvious.

Read recent n8n logs Use when the editor, webhook, or startup path fails.

docker compose logs n8n --tail=100

Secrets note: Review before sharing; remove tokens, private hostnames, and customer payloads.
Verification: The log contains a timestamped error, migration message, or clean startup line.

Check public URL variables only Use when webhook URLs show localhost, http, or the wrong domain.

docker compose exec n8n printenv WEBHOOK_URL N8N_HOST N8N_PROTOCOL N8N_EDITOR_BASE_URL

Secrets note: Do not run a full env dump in public channels; print only these non-secret routing names.
Verification: Values point to the intended HTTPS public domain.

Safe Copyable Config

Backup and restore checklist Use before upgrades, host moves, and restore drills.

# 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.sql

What to change: Use your real private database connection locally. Add binary data and volume backups based on your storage mode.
Secrets to keep private: Database password N8N_ENCRYPTION_KEY credential exports binary files containing customer data
Verification: A restored test instance can open workflows, decrypt credentials, and run a smoke test.
Common mistakes: Testing restore for the first time during an outage. Forgetting N8N_ENCRYPTION_KEY. Backing up the database but not binary data.

Docker Compose with Postgres for n8n data Use when SQLite is no longer enough or when planning queue mode later.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n_app
      - POSTGRES_PASSWORD=REDACTED_CHANGE_ME
    volumes:
      - postgres_data:/var/lib/postgresql/data

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      - 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_ONCE
      - WEBHOOK_URL=https://automation.example.com/
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  postgres_data:
  n8n_data:

What to change: Generate a strong database password and N8N_ENCRYPTION_KEY privately. Back up both Postgres and n8n binary data storage.
Secrets to keep private: POSTGRES_PASSWORD DB_POSTGRESDB_PASSWORD N8N_ENCRYPTION_KEY
Verification: n8n starts without migration errors. A restart preserves workflows and credentials decrypt successfully.
Common mistakes: Changing N8N_ENCRYPTION_KEY after credentials exist. Backing up only the n8n volume while the database holds production state.

Warnings

A database backup without the encryption key may not be enough to recover credentials.
A Docker volume snapshot is not a substitute for a tested restore.

Best For

Self-hosted n8n instances with real workflows or credentials.
Teams preparing for upgrades, migrations, or server moves.
Deployments using Docker volumes, SQLite, Postgres, or community nodes.

Not For

Disposable demo instances with no important data.
Users who cannot securely store encryption keys and database dumps.
Managed environments where backups are handled and verified by the provider.

Common Mistakes

Backing up only the Docker Compose file and not the database or volume data.
Losing the encryption key needed for credential recovery.
Never testing restore until a real outage.
Forgetting community node packages that workflows depend on.

Examples

Backup inventory Record where each durable piece of data lives.

Active database: SQLite or Postgres
n8n user data directory: backed up
Encryption key: stored securely
Community nodes: documented and restorable
External binary storage: included if used
Restore test date: recorded

Restore drill A backup is only real after a restore test.

1. Start a clean test instance.
2. Restore database and user data.
3. Provide the same encryption key.
4. Start n8n.
5. Open workflows and test one credential-backed execution.
6. Document what failed.

FAQ

What is the most commonly missed backup item?

The encryption key and the actual active database are easy to miss. Without them, workflows or credentials may not recover correctly.

Do I need backups before every upgrade?

Yes for any important self-hosted instance. Upgrades are one of the moments when a recent restore-tested backup matters most.

Is exporting workflows enough?

No. Workflow export can help, but it is not a full backup of credentials, execution data, settings, user data, and installed community packages.

Sources

n8n Supported Databases Accessed 2026-05-07 Update self-hosted n8n Accessed 2026-05-07 n8n Docker Installation Accessed 2026-05-07