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
| Where | Where to see the error |
|---|---|
| Connection test in the connection dialog | The 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 SQL | The error and SQLSTATE appear in the result area (SQL editor). |
| Background jobs such as exports and backups | In 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 place | Click 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
| Symptom | Cause | What to do |
|---|---|---|
| The web app shows Desktop-only Connection | The 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 localhost | Use 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 dialog | The NeoSQL server could not reach that database. It is inside an internal network or VPN, or the database firewall blocks connections from the NeoSQL server | Connect 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 notification | This PC could not reach the database. The address or port is wrong, the database is down, the VPN dropped, or a firewall blocks it | Check 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 host | The same network problems as above. Timeouts are common when a firewall drops the connection without answering | As above. The connection timeout is among the DBMS default properties on the Properties tab of the connection dialog |
Access denied, password authentication failed, Login failed | The 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 MariaDB | The server public key could not be fetched for caching_sha2_password authentication | Turn 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 found | The custom driver the connection uses is not on this PC. Common for connections created on another PC | When 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 driver | The driver class name is wrong, or the driver does not match the database version | Check the driver's class name and version (Driver management) |
| It connects, but no schemas appear in the explorer | Only the schemas chosen on the Schema tab of the connection dialog are shown | Choose schemas on the schema tab and save. For newly created schemas, reload the list with the Refresh Schemas button |
SSL and SSH tunnels
| Symptom | Cause | What to do |
|---|---|---|
| An error that the certificate name differs from the address | You connect by IP address, alias, or SSH tunnel, so the certificate's host name and the address differ. It happens even with a healthy server | Switch 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 certificates | Add that server's CA certificate on the SSL/SSH tab |
| A certificate validity error | The server certificate has expired, or this PC's clock is wrong | Ask your database administrator about renewing the certificate, and correct the PC's clock |
| TLS handshake failure | The server does not support SSL, or the protocol or cipher suites do not match | Check that SSL is enabled on the server; if unsure, ask your database administrator which TLS versions it supports |
SSH private key not configured | SSH authentication is set to the Public Key method but there is no private key | Add the private key on the Private Key row |
SSH private key file not found | The connection points to a key file path that is not on this PC | Upload 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 app | In the web app the NeoSQL server connects to the SSH server, and the SSH server is not reachable from the internet | If 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.
- Get your company's root certificate file (
.pem,.crt,.cer) from your network administrator. - Put the file in the folder shown under Certificate folder in the dialog. App updates do not remove this folder.
- 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).
| Symptom | Cause | What to do |
|---|---|---|
| Right after launch, an error window says the Java runtime was not found, and the app closes | The installation is damaged, or antivirus removed files inside the app | Download 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 closes | No usable port is available | Restart the PC, then start the app |
| The app opens, but everything involving databases fails | The local server failed to start or stopped | Quit 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
| Symptom | Cause | What to do |
|---|---|---|
| The Loading project data... screen stays for a long time | It is the first time on this device, or there are many documents to receive from the server. The number received is shown | Wait. 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 appears | The project could not sync with the server when opening | Check your internet connection and click the Retry button |
| Failed to load project information. Would you like to retry? appears | The project information could not be read from the server | Click 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. appears | Browser or site data was cleared while the app was open, cutting the connection to on-device storage | Click the Refresh button |
| A Reload project dialog appears | While you were not viewing this project, the server's sync history was cleaned up | Reload 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 header | While signed in, the app could not talk to the NeoSQL server | Click 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 appears | Another device or teammate saved the same document first | Choose 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. appears | The ERD is a team ERD on the server, but this device's sync is behind | Close the project and open it again |
You cannot enter a project
| Symptom | Cause | What to do |
|---|---|---|
| Project Under Cleanup appears | The project's plan was lowered and the owner has not yet chosen which members to keep | Wait 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. appears | Plan cleanup deactivated you in this project | Ask the project owner to reactivate you |
| Clicking a project on Home shows Management-only project | A workspace member created the project. The workspace owner only manages it | To 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 PC | Local projects are stored only on the PC that created them | Open it in the desktop app on that PC. Create projects you want to use on several devices as account projects |
| Projects disappeared after signing out | Signing out removes account projects from Home. They are not deleted | Sign in again with the same account (Sign-in and project types) |
Signing in
| Symptom | Cause | What to do |
|---|---|---|
| You clicked Sign In with Browser in the desktop app but no browser tab appears | The browser opened behind other windows or did not open | Click 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 app | You did not allow the browser's prompt to open the NeoSQL app | Allow opening the app in the browser's prompt (First run) |
| The Email verification is pending screen appears | You have not verified your sign-up email yet | Find 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 working | Your sign-in expired | Sign in again. If you were viewing a local project in the desktop app, you carry on without signing in |
| You forgot your password | You reset it through your sign-up email | Password explains how to reset it |
Updating
| Symptom | Cause | What to do |
|---|---|---|
| A Update Check Failed notification appears | The NeoSQL server could not be reached | Check your internet connection and check again later |
| A Update download unavailable notification appears | A new version is out, but its files are not uploaded yet | Check again later |
| An Update Error mark stays in the header | The update could not be downloaded or installed. Corporate networks often block downloads from GitHub | Download 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 deployed | A new version was deployed | Save your work and click the Refresh button |
| Windows SmartScreen warns, or macOS asks whether to open | This is the check for an app downloaded from the internet the first time it opens | Install and update explains how to check the publisher |
Exports and backups fail
| Symptom | Cause | What to do |
|---|---|---|
| In the web app, export or backup menus show This feature is only available in the desktop app. | The menu, the menu, the menu, and the menu are features where the local server writes and reads files on this PC | Use the desktop app (Web and desktop) |
| An Excel export fails | A value exceeds the per-cell limit (32,767 characters), and the Long text handling (cells over 32,767 chars) option is set to fail | Choose continue or truncate, or export as CSV or JSON (Exporting results) |
The file name ends in _lossy | Some values could not be written as they were because of the format's limits. The original data cannot be restored from that file | See Exporting results for when loss happens |
| The web app returns results only up to a limit | The web app limits rows for SQL results and exports by plan | Use the desktop app or check your plan (Plans and features) |
| Native Backup fails | The DBMS dump tool (pg_dump, mysqldump, and so on) is not on this PC, or a different executable was chosen | Install 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 restored | The dump tool and the server have different major versions | Back up again with a tool of the same major version as the server |
| A watermark appears on ERD images | You are not signed in, or your plan adds a watermark | See 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.
| Symptom | Cause | What to do |
|---|---|---|
neosql is missing from the client's MCP server list, or shows as failed | The client was not restarted after the config was added, the client cannot find npx, or Node.js is older than 20 | Restart 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 Code | Both a config (registered from the app or added manually) and the plugin are present | Turn one off with /mcp in Claude Code |
installation_not_found | The 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 installer | Install 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_found | The config was not made by the NeoSQLEnterprise app. The Claude plugin and configs that run npx connect to the NeoSQL app | Register again from the NeoSQLEnterprise app (Install and connect MCP) |
After you move or reinstall NeoSQLEnterprise, the client cannot start the neosql MCP server | The path of the app's executable or of the MCP server file in the config has changed | Register again from the NeoSQLEnterprise app |
activation_failed, installation_check_failed, status_check_failed | The MCP server could not launch the desktop app, or could not check its installation or state | Open the app yourself and ask again after the project opens |
readiness_timeout | The app or the project was not ready within 40 seconds. The request was not sent to the app | Check 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_ready | The app is running but is still loading its screen or the project | Ask again after the app finishes opening |
project_not_selected | No project is open in the desktop app | Open a project in the app, or ask the external AI to list the projects and pick one |
authentication_required, unauthenticated | The target is an account project, but you are not signed in to the desktop app | Sign in to the app. Without signing in, only local projects are handled |
user_action_required | Something 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 confirm | Handle it on the app screen and ask again |
project_load_failed | The project failed to load | Fix the error shown in the app and ask again |
target_unavailable, project_lookup_failed, project_navigation_failed, project_mismatch | The 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 project | Check the project ID and your access, return to the target project in the app, and ask again |
project_conflict | The 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 sent | Work in the fixed project. To work with other projects too, remove --project-id from the client's config |
unresponsive | A request sent to the app did not finish within the time limit. The request was sent once and is not sent again | The 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.
Related screens
- Create and edit a connection: the connection test and connection fields.
- SSL/TLS and SSH tunnels: secure connection and tunnel options.
- Web and desktop: the databases each app can reach.
- Install and update: installing, updating, and environments without internet.
- Install and connect MCP: installing the MCP server in an external AI client and checking the connection.
- FAQ: questions rather than problems.
- Database reference: connection fields and SSL modes that differ by DBMS.