Troubleshooting information that can help you diagnose and correct a problem.

You can review the Operations Manual → Neo4j log files to monitor the upgrade process and verify that no problems occur as it progresses. If a problem occurs, the following known troubleshooting information can help you diagnose and correct the problem.

Solutions to common problems

Calling dbms.upgrade results in a failure

The upgradeResult field describes which components have failed to upgrade.


To troubleshoot the root cause there are two things to try:

  • Call the more verbose version of the command — dbms.upgradeDetails, which returns a message with the underlying exception thrown. This might not be the root cause, but can help narrow it down.

  • Look for descriptive warnings and errors in the security.log and the debug.log. Stack traces should help track down the root cause of the problem.

Trying to upgrade between incompatible versions, for example migrating from Neo4j 3.5 to Neo4j 4.1

When the detected version of the system database is too old, the status code is one of the following:

  • UNSUPPORTED_BUT_CAN_UPGRADE - the server shuts down.


    Configure dbms.mode=SINGLE. This enables the automatic upgrade of the system database schema as the setting dbms.allow_single_automatic_upgrade is true by default when dbms.mode=SINGLE.

  • UNSUPPORTED - the server shuts down.


    No direct upgrade is possible, upgrade first to a supported intermediate version.

Calling dbms.upgrade when not all instances have been upgraded to the new version of Neo4j

  • Calling dbms.upgradeStatus on any instances still running the older version returns UNSUPPORTED_FUTURE.

  • These older instances are no longer able to authorize users.

  • All queries against these instances result in an error.


    Shut down, upgrade, and restart the instance in order to regain service.

Status codes for dbms.upgradeStatus

Table 1. System component status
Status Description Resolution


No sub-graph detected for this component.

Requires initialization.


The sub-graph is already at the current version.

No action required.


The sub-graph is supported but is an older version and requires upgrade.

Run CALL dbms.upgrade().


The sub-graph is unsupported; this component cannot function.

Restart Neo4j in a single-instance mode to upgrade this component at startup.


The sub-graph is unsupported because it is too old; this component cannot function.

Downgrade Neo4j and then upgrade this component before upgrading Neo4j again.


The sub-graph is unsupported because it is a newer version; this component cannot function.

Upgrade Neo4j.