Troubleshooting

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.

Solution

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.

    Solution

    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.

    Solution

    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.

    Solution

    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

UNINITIALIZED

No sub-graph detected for this component.

Requires initialization.

CURRENT

The sub-graph is already at the current version.

No action required.

REQUIRES_UPGRADE

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

Run CALL dbms.upgrade().

UNSUPPORTED_BUT_CAN_UPGRADE

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

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

UNSUPPORTED

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.

UNSUPPORTED_FUTURE

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

Upgrade Neo4j.