n8n 2.33.7 Stable vs 2.34.4 Beta: Safe Self-Hosted Upgrade Checks

Confirm the channel before changing anything#

Do not infer the channel from a Docker tag such as latest. Check the package registry and the release page from the environment where you are planning the change:

1
npm view n8n dist-tags --json
2
npm view n8n@latest version engines --json
3
npm view n8n@beta version --json

The current check returns 2.33.7 for latest and 2.34.4 for beta. The latest package also declares Node.js >=22.22. If you install n8n with npm rather than Docker, verify the runtime before the upgrade:

1
node --version
2
n8n --version

The 2.34.4 pre-release notes include a task-runner health-check fix and a fix for out-of-scope display-option dependencies. Those notes are useful for deciding whether a beta test addresses a problem you actually have; they are not a reason to move a production instance to a pre-release automatically. Release notes are a compatibility clue, not a substitute for testing your own database, queue, and runner setup.

Make the deployment reproducible#

Before upgrading, record the exact image or package version, database type, queue mode, worker count, task-runner mode, and n8n configuration variables. A short inventory makes a rollback much less ambiguous:

1
application: 2.33.7
2
database:    PostgreSQL 16
3
mode:        regular or queue
4
workers:     0, 2, ...
5
runners:     external or internal
6
storage:     local or external

Pin the version in your deployment definition instead of relying on a moving tag. Keep the same image family you already use, changing only the tag. For example, an installation using the official n8n image can make the version explicit:

1
services:
2
  n8n:
3
    image: docker.n8n.io/n8nio/n8n:2.33.7

If your compose file has separate worker or runner services, pin them to the same version. n8n’s external-storage guidance calls out version alignment across the main process, workers, and runners because their payloads and APIs must remain compatible during an upgrade.

Back up the data that rollback depends on#

Take a tested database backup and record where the n8n encryption key comes from. Preserve the configuration needed to mount the n8n data directory and any external binary storage. A container image can be replaced quickly; credentials, execution data, and encryption settings cannot be reconstructed from it.

For a small Docker Compose deployment, the safe sequence is conceptually:

1. Pause new executions or put the instance into the maintenance procedure your team uses.
2. Take the database and persistent-volume backups.
3. Save the current deployment definition and image digest.
4. Change the application tag to the target version.
5. Start the main process, workers, and runners together.

Do not delete the old image or backup until the new version has passed its checks. If a migration has changed the database schema, rolling back the container alone may not be sufficient; restore the matching data backup only after deciding whether the failed upgrade wrote data that must be preserved.

Upgrade a Compose deployment#

Replace service names with the ones in your own file. Pulling and recreating all n8n components in one maintenance window avoids a main process talking to workers from a different release:

1
docker compose config --quiet
2
docker compose pull n8n worker runner
3
docker compose up -d n8n worker runner
4
docker compose ps

If you do not run a worker or runner, omit that service rather than inventing a placeholder in the command. For a queue-mode installation, check that the queue backend is healthy before opening the editor to users.

Keep a development watcher separate from this release procedure. The Docker Compose Watch guide explains how source sync and dependency rebuilds work locally; an n8n version change still needs a pinned image, data backup, and coordinated service restart.

Verify the running version from inside the actual application service and inspect startup logs:

1
docker compose exec n8n n8n --version
2
docker compose logs --tail=100 n8n

Then exercise a low-risk workflow, confirm credentials can be resolved, and verify that a queued execution reaches a worker when queue mode is enabled. Check binary data separately if your workflows use files, because a successful editor login does not prove that external storage is configured correctly.

Decide whether a beta test is worth the risk#

Use 2.34.4 in a disposable or separately backed-up environment when you need to validate one of its fixes, test a new integration, or prepare a planned production upgrade. Keep the test representative: use the same database engine, queue settings, runners, and reverse proxy behavior as production.

Stay on 2.33.7 for production when you do not need a preview fix. A beta label is a release-channel signal, not a quality rating; it means your rollback and compatibility checks need to carry more weight.

After either upgrade, run the built-in audit command from the application environment and review the result with the same care as a dependency update:

1
n8n audit

The n8n security-audit documentation explains what the report checks. Also review the official update guidance for the installation method you use.

FAQ#