neo4j error: store migration failed - how to roll back a failed upgrade

TL;DR

Neo4j upgrades the store files automatically on first start of the new version, and there is no automatic rollback: a failed migration means restoring from the backup you took before upgrading. Restore the backup, fix the cause (usually disk space, permissions, or an incompatible plugin), and retry the upgrade. The backup is the entire recovery plan, so verify it before you start.

The query

neo4j error: store migration failed - how to roll back a failed upgrade

Use this when

• neo4j store migration failed during upgrade
• Neo4j will not start after a version upgrade
• Need to roll back a failed neo4j upgrade
• An agent upgraded neo4j and the store is wedged

Not for

• Cypher query errors after a good upgrade (a query problem)
• Driver or connection issues (check the connector)
• A store migration that succeeded but the app misbehaves (validate the app)

Steps

1. Stop neo4j and assess the damage

neo4j stop
grep -i "migration" /var/log/neo4j/debug.log | tail -30

Expected output: the log lines showing where the store migration failed. Note the cause: out of disk, permission denied, and plugin incompatibility are the big three.

2. Restore the pre-upgrade backup

neo4j-admin database restore --from-path=[backup path] [database]

Expected output: the database files return to their pre-upgrade state. This is the rollback: neo4j cannot roll a store migration back, only a restore can.

3. Verify the restored database starts on the OLD version

Start neo4j with the previous version and confirm the database comes online and the data is intact. Expected output: a healthy database on the old version. Do not proceed until this is true: it proves the backup was good.

4. Fix the cause of the failure

Disk space: free or add space (store migration needs headroom for both formats). Permissions: ensure the neo4j user owns the data directories. Plugins: upgrade APOC and other plugins to versions built for the target neo4j version, or remove them for the migration.

Expected output: the specific cause from step 1 is eliminated, not just suspected gone.

5. Retry the upgrade

Start the new version again and watch the migration logs to completion. Expected output: the store migration completes and the database comes online on the new version. Keep the backup until the new version has run cleanly for a full cycle.

Tool compatibility

neo4j 5.x. Store migration on first start and neo4j-admin restore work the same across 5.x.

Variant phrasings

neo4j store migration failed how to roll back

Steps 1 and 2: stop, restore the backup. There is no in-place rollback for store migrations.

neo4j will not start after upgrade store migration

Step 4: read the debug log first. Disk, permissions, and plugins cover nearly every case.

neo4j upgrade failed plugin incompatible

Step 4: upgrade or remove the plugin, then retry. Plugins must match the neo4j major version.

Why it happens

Neo4j migrates store files forward automatically because the format changes between majors, and the migration rewrites files in place. There is no backward migration: the old version cannot read the new format, and a half-migrated store is unreadable by either version. The backup is therefore not a precaution but the rollback mechanism itself.

Edge cases

• A backup taken AFTER the failed migration started is worthless: it contains half-migrated files. Verify backup timestamps predate the upgrade attempt.
• Test the restore procedure on a scratch machine before the real upgrade: an untested backup is a hope, not a plan.
• Cluster upgrades need every member migrated: a restored single instance rejoining a migrated cluster will not work. Plan the cluster procedure, not just one node.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_90I5-2icDLZtScV8xjRKgQ