Neo4j Admin Upgrade: Recovering from an In‑Place Upgrade Failure

Answer

Neo4j does not ship a rollback command for neo4j-admin upgrade. The only supported recovery path is to restore the data directory from a pre‑upgrade backup. If the upgrade was interrupted before the store reached a stable upgraded state, the store files may be in a mixed format and cannot be safely rolled back by editing files.

Likely Explanation

• During an in‑place upgrade Neo4j writes new store files next to the old ones. A crash can leave both sets present.
• Without a dedicated rollback API, the database engine cannot automatically decide which files to keep.
• Attempting to delete or rename store files manually risks further corruption.

Steps to Recover

1. Stop the Neo4j service if it is still running.

   sudo systemctl stop neo4j
   

2. Verify the current store with a consistency check. This does not attempt to repair but reports errors.

   neo4j-admin check-consistency --report-dir=/tmp/consistency-report
   

   Check the report.txt for any "ERROR" lines.

3. Inspect neostore.properties in the data directory. The store.version entry should match the target Neo4j version you intended to upgrade to. If it shows a value from the previous version or is duplicated, the store is incomplete.

4. Restore from a full backup taken before the upgrade. Replace the entire data/data/ directory with the backup contents. Ensure the backup includes the transaction log directory if you wish to recover post‑commit changes.

5. Start Neo4j and confirm that neo4j.log contains no recovery failures.

   sudo systemctl start neo4j
   journalctl -u neo4j -f
   

6. Re‑attempt the upgrade only after confirming the restored store is healthy.

Verification Steps

• Run neo4j-admin check-consistency again after restoration; the report should contain zero errors.
• Open neostore.properties and confirm a single store.version line matching the target Neo4j edition.
• Check that the transaction directory exists and is writable.

Transaction Log Considerations

The transaction log directory is not part of neo4j-admin backup. If the log files were not corrupted during the failed upgrade, Neo4j will attempt an automatic recovery on startup. However, any transactions committed after the backup but before the upgrade attempt will not be present in the log and are lost. Because log integrity cannot be guaranteed without a full audit, relying solely on the log is risky.

Missing Diagnostic Detail

To decide whether you can attempt a log‑only recovery, please confirm:
Did the transaction directory remain unmodified and intact after the upgrade failure?