Reference

Troubleshooting

This page lists problems you are likely to meet in NeoSQL as symptom, cause, and what to do. Look up the message shown on screen, and read the linked page to understand the cause. If nothing here solves it, report it with the Bug report panel.

Check the error message first

WhereWhere to see the error
Connection test in the connection dialogThe red icon next to the Test Connection button. After the error closes, click the icon to see the database's error again (Create and edit a connection).
Running SQLThe error and SQLSTATE appear in the result area (SQL editor).
Background jobs such as exports and backupsIn the Background Processes popover on the status bar, copy the error of a failed job or retry it (App menu, top bar and status bar).
An error you cannot placeClick the Report a bug button in the header; the recent errors since the app started are collected in its error log.

Errors returned by the database are shown as they are, untranslated. The English errors in the tables below are examples of that raw text.

The database does not connect

SymptomCauseWhat to do
The web app shows Desktop-only ConnectionThe connection is SQLite, H2 Embedded, or localhost. In the web app the NeoSQL server connects to databases, so it cannot reach files on your PC or your localhostUse the desktop app. To use it in the web app, create the connection with a host reachable from the internet (Web and desktop)
The web app shows a Cannot connect to the database dialogThe NeoSQL server could not reach that database. It is inside an internal network or VPN, or the database firewall blocks connections from the NeoSQL serverConnect to internal databases with the desktop app. If the database is open to the internet, check its address, DNS, and firewall. If you have an SSH server reachable from the internet, you can connect through an SSH tunnel
The desktop app shows a Database unreachable notificationThis PC could not reach the database. The address or port is wrong, the database is down, the VPN dropped, or a firewall blocks itCheck the host and port, that the database is running, and that the VPN is connected. If other tools on this PC cannot connect either, ask your network administrator about the firewall
Connection refused, connect timed out, Communications link failure, Unknown hostThe same network problems as above. Timeouts are common when a firewall drops the connection without answeringAs above. The connection timeout is among the DBMS default properties on the Properties tab of the connection dialog
Access denied, password authentication failed, Login failedThe database was reached, but the user or password is wrong, or the user may not connect from this PC (or from the NeoSQL server)Enter the user and password again. MySQL and MariaDB allow each user only from set hosts, so check with your database administrator
Public Key Retrieval is not allowed on MySQL or MariaDBThe server public key could not be fetched for caching_sha2_password authenticationTurn on the Public key retrieval option on the SSL/SSH tab, or turn on SSL (SSL/TLS and SSH tunnels)
The connection dialog shows Custom driver "…" not found locally. Install it from Driver Manager., or No suitable driver foundThe custom driver the connection uses is not on this PC. Common for connections created on another PCWhen a project opens, the desktop app offers the Install Missing Driver dialog to upload the JAR or use the default driver with the Replace with bundled driver JAR option. The web app uses default drivers only (Driver management)
The connection test fails after adding a custom driverThe driver class name is wrong, or the driver does not match the database versionCheck the driver's class name and version (Driver management)
It connects, but no schemas appear in the explorerOnly the schemas chosen on the Schema tab of the connection dialog are shownChoose schemas on the schema tab and save. For newly created schemas, reload the list with the Refresh Schemas button

SSL and SSH tunnels

SymptomCauseWhat to do
An error that the certificate name differs from the addressYou connect by IP address, alias, or SSH tunnel, so the certificate's host name and the address differ. It happens even with a healthy serverSwitch to the Verify CA mode to keep certificate verification and skip only the host name check
An error that the server certificate cannot be trusted (PKIX path building failed and similar)NeoSQL does not know the CA that issued the server certificate. Common with self-signed certificatesAdd that server's CA certificate on the SSL/SSH tab
A certificate validity errorThe server certificate has expired, or this PC's clock is wrongAsk your database administrator about renewing the certificate, and correct the PC's clock
TLS handshake failureThe server does not support SSL, or the protocol or cipher suites do not matchCheck that SSL is enabled on the server; if unsure, ask your database administrator which TLS versions it supports
SSH private key not configuredSSH authentication is set to the Public Key method but there is no private keyAdd the private key on the Private Key row
SSH private key file not foundThe connection points to a key file path that is not on this PCUpload the private key again. The uploaded key's content is stored in the connection, so it also works on other PCs and in the web app
The SSH tunnel does not connect in the web appIn the web app the NeoSQL server connects to the SSH server, and the SSH server is not reachable from the internetIf the SSH server is only on the internal network, use the desktop app

What each SSL mode verifies is explained under "Secure connections" in Connections and execution targets.

A certificate notice on a corporate network

If the desktop app shows a Security certificate is not trusted dialog, SSL inspection by a corporate firewall, antivirus, or VPN is swapping certificates, so the app's local server did not trust the NeoSQL server. The browser uses the operating system's certificates and looks fine, while only the app fails.

  1. Get your company's root certificate file (.pem, .crt, .cer) from your network administrator.
  2. Put the file in the folder shown under Certificate folder in the dialog. App updates do not remove this folder.
  3. Quit the app completely and start it again.

The desktop app's local server does not start

When it starts, the desktop app also starts the local server that connects to databases on this PC. The local server runs on the Java runtime bundled with the app and uses the first free port from 52080 up, or from 52180 for NeoSQLEnterprise (Install and update).

SymptomCauseWhat to do
Right after launch, an error window says the Java runtime was not found, and the app closesThe installation is damaged, or antivirus removed files inside the appDownload the installer from the website and install again. Reinstalling keeps your local projects and settings
Right after launch, an error window says no server port was found, and the app closesNo usable port is availableRestart the PC, then start the app
The app opens, but everything involving databases failsThe local server failed to start or stoppedQuit the app completely and start it again. On start, the app cleans up any local server left from last time and starts a new one. If it keeps happening, tell us with a Bug report

Opening or syncing an account project

SymptomCauseWhat to do
The Loading project data... screen stays for a long timeIt is the first time on this device, or there are many documents to receive from the server. The number received is shownWait. After a few seconds a Cancel and go to Dashboard button appears so you can go back home. For projects with many deletion records, the owner can clean up sync data in Project settings to speed this up
The Failed to sync project data. Please check your network connection. screen appearsThe project could not sync with the server when openingCheck your internet connection and click the Retry button
Failed to load project information. Would you like to retry? appearsThe project information could not be read from the serverClick the Retry button
The local database connection was lost. This can happen after clearing browser/site data while the app is open. Refresh the app to reconnect. appearsBrowser or site data was cleared while the app was open, cutting the connection to on-device storageClick the Refresh button
A Reload project dialog appearsWhile you were not viewing this project, the server's sync history was cleaned upReload it. If you postpone, changes in the meantime stay only on this device
A Can't reach the NeoSQL server, so your plan and account projects couldn't be loaded. bar appears under the headerWhile signed in, the app could not talk to the NeoSQL serverClick the Retry button. Local projects keep working meanwhile (App menu, top bar and status bar)
An ERD Sync Conflict dialog or SQL Sync Conflict dialog appearsAnother device or teammate saved the same document firstChoose whether to save yours or replace it with the server's (Collaboration and permissions)
After moving to a team ERD, The ERD was shared, but local synchronization is delayed. Reopen the project to continue safely. appearsThe ERD is a team ERD on the server, but this device's sync is behindClose the project and open it again

You cannot enter a project

SymptomCauseWhat to do
Project Under Cleanup appearsThe project's plan was lowered and the owner has not yet chosen which members to keepWait until the owner enters the project and finishes the cleanup (Plans and features)
This project has reached its share-member limit. Please contact the project owner. appearsPlan cleanup deactivated you in this projectAsk the project owner to reactivate you
Clicking a project on Home shows Management-only projectA workspace member created the project. The workspace owner only manages itTo work in it, ask that member to invite you to the project (Workspaces)
A local project does not appear in the web app or on another PCLocal projects are stored only on the PC that created themOpen it in the desktop app on that PC. Create projects you want to use on several devices as account projects
Projects disappeared after signing outSigning out removes account projects from Home. They are not deletedSign in again with the same account (Sign-in and project types)

Signing in

SymptomCauseWhat to do
You clicked Sign In with Browser in the desktop app but no browser tab appearsThe browser opened behind other windows or did not openClick the Go back and try again link on the waiting screen and try again
You signed in in the browser but did not return to the appYou did not allow the browser's prompt to open the NeoSQL appAllow opening the app in the browser's prompt (First run)
The Email verification is pending screen appearsYou have not verified your sign-up email yetFind the verification email in your inbox or spam folder and click its link; if it is not there, click the Resend verification email button (Sign-up and sign-in)
A Your session has expired. Please sign in again. notification appears while workingYour sign-in expiredSign in again. If you were viewing a local project in the desktop app, you carry on without signing in
You forgot your passwordYou reset it through your sign-up emailPassword explains how to reset it

Updating

SymptomCauseWhat to do
A Update Check Failed notification appearsThe NeoSQL server could not be reachedCheck your internet connection and check again later
A Update download unavailable notification appearsA new version is out, but its files are not uploaded yetCheck again later
An Update Error mark stays in the headerThe update could not be downloaded or installed. Corporate networks often block downloads from GitHubDownload the new installer from the website and install it. Projects and settings are kept (Install and update)
The web app shows A new version has been deployedA new version was deployedSave your work and click the Refresh button
Windows SmartScreen warns, or macOS asks whether to openThis is the check for an app downloaded from the internet the first time it opensInstall and update explains how to check the publisher

Exports and backups fail

SymptomCauseWhat to do
In the web app, export or backup menus show This feature is only available in the desktop app.The Explorer context menuData Export... menu, the Explorer context menuData Import... menu, the Explorer context menuNative Backup... menu, and the Explorer context menuNative Reload... menu are features where the local server writes and reads files on this PCUse the desktop app (Web and desktop)
An Excel export failsA value exceeds the per-cell limit (32,767 characters), and the Long text handling (cells over 32,767 chars) option is set to failChoose continue or truncate, or export as CSV or JSON (Exporting results)
The file name ends in _lossySome values could not be written as they were because of the format's limits. The original data cannot be restored from that fileSee Exporting results for when loss happens
The web app returns results only up to a limitThe web app limits rows for SQL results and exports by planUse the desktop app or check your plan (Plans and features)
Native Backup failsThe DBMS dump tool (pg_dump, mysqldump, and so on) is not on this PC, or a different executable was chosenInstall the dump tool and choose its executable in the Local client field. Once chosen, it is run once to show its version (Data export, import and native backup)
A PostgreSQL backup file cannot be restoredThe dump tool and the server have different major versionsBack up again with a tool of the same major version as the server
A watermark appears on ERD imagesYou are not signed in, or your plan adds a watermarkSee the watermark rules in Export as image

MCP does not connect

When the external AI cannot call NeoSQL tools, check the tool result the client shows. Most failed results contain a status value and a message in English. Installation is explained in Install and connect MCP.

SymptomCauseWhat to do
neosql is missing from the client's MCP server list, or shows as failedThe client was not restarted after the config was added, the client cannot find npx, or Node.js is older than 20Restart the client. Check the Node.js version with node --version in a terminal. If it works in a terminal but not in the client, check that Node.js is on the PATH the client sees
The NeoSQL tools appear twice in Claude CodeBoth a config (registered from the app or added manually) and the plugin are presentTurn one off with /mcp in Claude Code
installation_not_foundThe MCP server could not find an installed desktop app. On macOS it looks in the Applications folders (/Applications, ~/Applications) and at the location the app records each time it starts. On Windows it looks for the app installed with the installerInstall the desktop app. If it is already installed, open the app yourself and ask again. On macOS, after you open the app once, it is found from then on
You use NeoSQLEnterprise, but the external AI opens the NeoSQL app or reports installation_not_foundThe config was not made by the NeoSQLEnterprise app. The Claude plugin and configs that run npx connect to the NeoSQL appRegister again from the NeoSQLEnterprise app (Install and connect MCP)
After you move or reinstall NeoSQLEnterprise, the client cannot start the neosql MCP serverThe path of the app's executable or of the MCP server file in the config has changedRegister again from the NeoSQLEnterprise app
activation_failed, installation_check_failed, status_check_failedThe MCP server could not launch the desktop app, or could not check its installation or stateOpen the app yourself and ask again after the project opens
readiness_timeoutThe app or the project was not ready within 40 seconds. The request was not sent to the appCheck the app for a loading error or a notice to confirm, and ask again after the project opens. If the app does not respond, restart it
app_not_readyThe app is running but is still loading its screen or the projectAsk again after the app finishes opening
project_not_selectedNo project is open in the desktop appOpen a project in the app, or ask the external AI to list the projects and pick one
authentication_required, unauthenticatedThe target is an account project, but you are not signed in to the desktop appSign in to the app. Without signing in, only local projects are handled
user_action_requiredSomething must be handled in the app before the project opens. Examples are unsaved changes, unlocking a project with ZK encryption, plan cleanup of connections or members, a custom driver missing on this computer, and a notice to confirmHandle it on the app screen and ask again
project_load_failedThe project failed to loadFix the error shown in the app and ask again
target_unavailable, project_lookup_failed, project_navigation_failed, project_mismatchThe target project (the one the external AI chose, or --project-id in the config) could not be opened, or the app's project changed during the request. The request stops instead of running in another projectCheck the project ID and your access, return to the target project in the app, and ask again
project_conflictThe project is fixed with --project-id in the config, but the external AI targeted another project or tried to create a new one. The request was not sentWork in the fixed project. To work with other projects too, remove --project-id from the client's config
unresponsiveA request sent to the app did not finish within the time limit. The request was sent once and is not sent againThe database or files may already have changed. Check the result before asking again

If it is still not solved

  • Send it from inside the app with the Bug report panel. The app version, OS, current screen, and recent errors are filled in for you.
  • If you cannot use the app, or it is a question rather than a problem, use the ways in Contact us.