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 thesystem
database schema as the settingdbms.allow_single_automatic_upgrade
istrue
by default whendbms.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 returnsUNSUPPORTED_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
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 |
|
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. |