Troubleshooting guide

This section describes common errors and solutions.

1. Log files

If something goes wrong, the logs are a good place to start. The neo4j.log for each DBMS can be accessed directly from Desktop and opens in a separate window, which allows you to keep it in the background. This is the standard log and contains general information about Neo4j. Please see Operations Manual → Logging for more information about other Neo4j log files. Desktop has its own log as well, with information about the application. The Desktop log file can be found here:

~/Library/Logs/Neo4j Desktop/main.log
~/.config/Neo4j Desktop/Application/log.log

Windows before 1.0.19:

%USERPROFILE%\AppData\Roaming\Neo4j Desktop\log.log

Windows after 1.0.19:

%USERPROFILE%\.Neo4jDesktop\ (or any other user defined path)

2. Installation or startup issues

If the application will not start when launched, a possible reason is that there already are other Desktop processes running. You can solve this by manually shutting down any running Desktop processes, using the your OS’s process manager. Once all Desktop processes have been terminated, you can re-launch Desktop.

If you run Desktop on Linux, this is the resulting error message:

node::NodePlatform::ForIsolate(v8::Isolate *): Assertion `data` failed.

3. Re-installation of Desktop

There may be situations where it is recommended to do a fresh install of Desktop. In such cases, it is important to make sure that your existing data is safe so you can import it into your new installation. The following steps guide you through the process:

  1. Locate the DBMS

    If you are not sure where it is located, see Locating a DBMS below. Remember that there may be multiple DBMSs in your installation.

  2. Do a manual dump to back up your data

    See Operations Manual → Back up an offline database. Keep in mind that you need to back up each database in each DBMS that you have in your current installation of Desktop. Also make sure to take note of all your Projects and DBMSs, including what version of Neo4j is used for each DBMS.

    The following step deletes all your data. Do not proceed unless you have completed the back up step.

  3. Tear down the current installation of Desktop

    Once you have securely backed up all of your databases, you need to tear down your installation of Desktop. This is done by deleting the following directories.

    - Relate cache: $HOME/Library/Caches/com.Neo4j.Relate
    - Relate config: $HOME/Library/Application\ Support/com.Neo4j.Relate
    - Relate data: $HOME/Library/Application\ Support/Neo4j\ Desktop/Application/relate-data
    - Neo4j Desktop Application files: $HOME/Library/Application\ Support/Neo4j\ Desktop
    - Neo4j Desktop binary e.g. /Applications/Neo4j
    - Relate cache: $HOME/.cache/neo4j-relate
    - Relate config: $HOME/.config/neo4j-relate
    - Relate data: $HOME/.local/.share/neo4j-relate
    - Neo4j Desktop Application files: $HOME/.config/Neo4j\ Desktop/
    - Neo4j Desktop AppImage

    Use the uninstaller to uninstall Neo4j Desktop, then delete the directories below.

    - Relate cache: %USERPROFILE%\AppData/Local\Neo4j\Relate/Cache
    - Relate config: %USERPROFILE%\AppData\Roaming\Neo4j\Relate\Config
    - Relate data: %USERPROFILE%\AppData\Local\Neo4j\Relate\Data

    If the data path has been changed in the app for Windows, you need to locate it and delete it.

  4. Download and install the new Desktop application

    Go to the Neo4j Download Center and select your OS. See Download and install for more information.

  5. Recreate your Projects and DBMS(s)

    Using your notes from the second step, recreate your Project(s) and DBMS(s) in your new installation of Neo4j Desktop. Make sure you use the same version of Neo4j for each DBMS as it had in your old installation.

  6. Import the database(s)

    From the appropriate DBMS, use the neo4j-admin load command to import the backed up databases. See Operations Manual → Restore a dump for more information on the neo4j-admin load command.

4. Cannot start a DBMS

In case starting a DBMS takes longer than 60 seconds, Desktop may show a timeout message even though the DBMS has actually started. To show the actual state, you can refresh Desktop (ctrl+r alternatively cmd+r).

For other issues related to starting a DBMS, you can find more information in the neo4j.log or the debug.log files in the DBMS folder. As mentioned above, the neo4j.log file is also accessible from the More Options dropdown menu for the DBMS in question.

5. Windows-specific DBMS errors

When running Desktop on Windows, PowerShell 5.1+ is required and it must be on the path for the application to function optimally. Possible issues related to PowerShell are for example that the DBMS will not start or that you are unable to change or set a password for your DBMS.

There are scenarios when PowerShell is missing from the path, for example after an OS update. In that case, you need to find environment variables in the System Properties menu and manually update your paths. Depending on where you have installed PowerShell, this is what the user path and system path can look like:


Once you have made sure that PowerShell 5.1+ is installed and on your path, it is recommended to restart Desktop.

6. Locating a DBMS

If you do not know the location of your DBMS, you can find it in More Options → Open folderDBMS.

The folder can be in different locations, depending what initial version of Desktop you installed and which version you used to create the DBMS. The following are possible locations:

~/Library/Application Support/Neo4j Desktop/Application/relate-data/dbmss
~/Library/Application Support/com.Neo4j.Relate/Data/dbmss
~/Library/Application Support/Neo4j Desktop/Application/neo4jDatabases
~/.config/Neo4j Desktop/Application/relate-data/dbmss
~/.config/Neo4j Desktop/Application/neo4jDatabases
%USERPROFILE%\.Neo4jDesktop could be a different user defined path.

7. Proxy issues

If you are experiencing connectivity issues or problems fetching the DBMS versions and/or plugins, the proxy settings is a possible cause. Below is a list of the URLs the Desktop uses to determine internet connection, supported plugins, plugin versions and Neo4j versions. These can be added to your proxy’s allowlist or equivalent in your setup.