Common Connection Errors & Fixes
A troubleshooting reference for errors that arise from NeoSQL's runtime environment (Web App · Desktop · Offline).
Reading the Error Message
When a connection test fails, a red X icon appears next to the Test Connection button.
Hovering or clicking the icon shows a tooltip with the full error message.
The error pattern differs by runtime environment (Web App / Desktop). Look up your case in the environment section below.
Errors common in Web App mode
In Web App mode, the embedded-server on NeoSQL's cloud servers connects to your DB. It therefore cannot reach anything in your local environment — local DBs, intranet hosts, or key files on your machine — and the errors below stem from that.
| Case | Example Message | Fix |
|---|---|---|
| Local DB blocked (SQLite · H2 Embedded · localhost) | This connection (SQLite / H2 Embedded / localhost, etc.) is available only in Desktop mode. | Local-host databases (SQLite, H2 Embedded, localhost, 127.0.0.1) cannot be reached from the cloud server. Use the Desktop app, or switch to a DB that is reachable from a public host. |
| Cannot reach a DB behind a corporate firewall / private subnet | Connection refused · connect timed out(happens even when host / port / credentials are all correct) | Web App's embedded-server cannot directly reach DBs in your private subnet. Options: • Use the Desktop app (connects directly from your PC) • Have an admin allow NeoSQL's server IP in your DB security group / firewall • Use an SSH tunnel via a jump host — note that key files only work in Desktop |
| SSH tunnel key file unavailable | SSH private key file not found: <path>or the SSH tunnel configuration is not applied | Web App cannot access the SSH key file on your PC and therefore does not support SSH tunneling. Use the Desktop app for DBs that require an SSH tunnel. |
Errors common in Desktop mode
| Case | Example Message | Fix |
|---|---|---|
| Custom JDBC driver not installed | Custom driver "<label>" not found locally. Install it from Driver Manager.or No suitable driver found for jdbc:<scheme>:... | Drivers that aren't bundled with NeoSQL must be registered manually. Open JDBC Driver Manager in the connection settings modal and upload the jar. (Not available in Web App — Desktop only.) |
| SSH private key file path / format error | SSH private key file not found: <path>SSH private key not configured | Re-upload the private key in the SSL/SSH tab's SSH Tunnel settings. PuTTY .ppk files aren't supported — convert them to OpenSSH format first. |
| (Offline) access to a DB not registered with the license | No dedicated error message. Blocked in two forms: • Project card shows a grey Disabled badge and clicking it does nothing • In the connection settings modal, the URL field becomes a select box limited to the JDBC URLs registered with the license | An Offline license operates only within the list of JDBC URLs registered at issuance. To use a DB at a different host, reissue the license from My Page (web) with the new URL added. Self-issued licenses are available on the TEAM plan. |