DBeaver troubleshooting: when it will not start, connect or update
Most DBeaver problems are one of four things: the JVM cannot start with the memory it was told to use, a workspace is locked by a process that already exited, a driver cannot be downloaded, or the operating system is blocking a freshly downloaded app. This page is organised by what you are seeing rather than by subsystem, so you can start from the symptom. Every fix is mechanical and checkable — where something is community-reported rather than documented by the vendor, it says so.
- covers 26.1.5
- OpenJDK 21 bundled
- no official failure index
- updated 2026-08-18
DBeaver troubleshooting at a glance
| what you see | most likely cause | first thing to try |
|---|---|---|
| Nothing happens on launch | JVM cannot allocate the configured heap | Lower -Xmx in dbeaver.ini |
| “Failed to create the Java Virtual Machine” | Same — the requested memory is unavailable | Halve the -Xmx value, save, relaunch |
| “Workspace in use or cannot be created” | Stale lock from a crashed session | Close all instances; delete the workspace .lock |
| Driver download fails | No route to the Maven repository | Set the proxy, or add the JAR manually |
| “Unidentified developer” / SmartScreen | OS check on newly downloaded apps | Right-click → Open (macOS); More info → Run anyway (Windows) |
| SSH tunnel cannot read your key | Snap confinement blocking ~/.ssh | Use the apt repo or .deb build instead |
| Out of memory on a big query | Heap too small for the result set | Raise -Xmx; lower the fetch size |
DBeaver is not starting
DBeaver troubleshooting nearly always starts here, because a DBeaver that dies before showing a window is almost always a Java heap problem. The launcher reads dbeaver.ini, asks the bundled OpenJDK 21 for the maximum heap named there, and exits if the operating system cannot hand over that much. On a machine with modest RAM — or one already running a browser with forty tabs — a generous -Xmx is exactly the kind of request that fails.
- Find
dbeaver.ini. It lives beside the application: the install folder on Windows, inside the app bundle on macOS (right-click DBeaver → Show Package Contents, then look under Contents), and the package's shared directory on Linux. A portable .zip or .tar.gz keeps it in the folder you unpacked. - Lower the heap. Find the line starting
-Xmx— for example-Xmx2048m— and halve it. Save the file. This is plain text; nothing needs rebuilding. - Launch from a terminal. If it still fails, running the executable from a terminal or command prompt prints the error that the double-click swallowed. That message is what turns guesswork into a fix — and it is what to paste if you open an issue.
- Try a clean start. Eclipse-based applications accept a
-cleanargument that discards cached plugin state, which clears failures that survive a restart but are not memory-related.
“Workspace in use or cannot be created”
DBeaver keeps one lock per workspace so two instances cannot corrupt the same settings. If a session crashes, that lock can outlive the process, and the next launch refuses to open a workspace nothing is actually using.
Close every DBeaver window and confirm no dbeaver process survives — Task Manager on Windows, Activity Monitor on macOS, pgrep -fl dbeaver on Linux. Start it again. If the same message appears with nothing running, the stale .lock file inside the workspace's .metadata folder is holding it; deleting that one file releases the workspace and keeps your connections and scripts intact.
Worth knowing before you delete anything: your connections, scripts and settings live in the DBeaverData workspace in your user profile, not in the install directory. That is why reinstalling almost never fixes a broken setup — the reinstall replaces the part that was fine and leaves the part that was not.
DBeaver troubleshooting for drivers that will not download
DBeaver ships without database drivers and fetches them from Maven repositories the first time you connect to a given engine. It is a deliberate design — it keeps installers in the 104–123 MB range instead of bundling every JDBC driver in existence — but it means the first connection needs outbound network access, which is exactly what corporate proxies and air-gapped machines do not provide.
Behind a proxy, configure it in DBeaver's preferences so driver downloads use the same route as the rest of your traffic. With no outbound access at all, add the driver JAR by hand in the driver editor; our offline installer guide walks through obtaining and registering driver JARs for a disconnected machine. Note that this is separate from the application download — every official DBeaver package is already a complete offline installer for the app itself.
Operating system warnings on first launch
Some DBeaver troubleshooting is not about DBeaver at all. On macOS, Gatekeeper may refuse to open a newly downloaded application, describing it as unverified or from an unidentified developer. Right-click the app in Applications, choose Open, and confirm once — full detail on the Mac download page. On Windows, SmartScreen may show a blue “Windows protected your PC” panel for an installer it has not seen often; More info → Run anyway proceeds.
Neither warning indicates a corrupted or tampered download, but both are a fair prompt to check the file if you did not get it from an official source. Every package's SHA-256 is published on our offline installer page, so you can verify with shasum -a 256 or Get-FileHash before running anything.
DBeaver troubleshooting FAQ
Why is DBeaver not starting at all?
In most reported cases the Java runtime cannot allocate the memory the configuration asks for, and DBeaver exits before drawing a window — often with “Failed to create the Java Virtual Machine”. Lower the -Xmx value in dbeaver.ini to something your machine can actually spare, save, and start again. If the window still never appears, launch from a terminal so you can read the error instead of guessing.
How do I fix "Failed to create the Java Virtual Machine" in DBeaver?
Edit dbeaver.ini and reduce the maximum heap. A line such as -Xmx2048m asks for 2 GB; if the machine cannot provide it — because RAM is small, or another process holds it — the JVM refuses to start. Halving the value is the usual fix. The setting is a plain text line, so no reinstall is needed.
What does "Workspace in use or cannot be created" mean?
Another DBeaver process is using that workspace, or a previous one crashed and left its lock file behind. Close every DBeaver window, confirm no dbeaver process is still running, then start it again. If the message persists with nothing running, a stale .lock file inside the workspace's .metadata folder is the cause and deleting that file releases it.
Why does DBeaver fail to download a database driver?
Drivers are fetched on demand from Maven repositories the first time you use a database type, so anything blocking that request — no internet, a corporate proxy, or an air-gapped machine — stops it. Configure the proxy in Preferences, or add the driver JAR by hand: our offline installer guide covers manual driver setup for machines with no outbound access.
Why can snap-installed DBeaver not see my SSH keys?
Snap's strict confinement isolates the application from dotfiles such as ~/.ssh, which breaks SSH-tunnel connections that need to read a private key — a long-standing community-reported limitation rather than a bug in DBeaver itself. Install from the apt repository or the .deb instead; see the Ubuntu guide.
DBeaver is slow or runs out of memory on large result sets. What helps?
Two levers. Raise -Xmx in dbeaver.ini so the JVM may use more RAM, and reduce how much data you pull at once — lower the fetch size, and avoid opening a multi-million-row table with no filter. These are the same trade-off from opposite ends: memory available versus memory demanded.
Does reinstalling DBeaver lose my connections and scripts?
No. Connections, scripts and settings live in a separate DBeaverData workspace folder in your user profile, not in the install directory — which is why reinstalling rarely fixes a broken setup, and why uninstalling does not clean it up. Delete the workspace folder deliberately if you want a genuine reset.
Where is dbeaver.ini on Windows, macOS and Linux?
It sits beside the application: in the installation folder on Windows, inside the application bundle on macOS (Show Package Contents, then look under Contents), and in the package's shared directory on Linux — typically under /usr/share for a .deb or .rpm install. A portable .zip or .tar.gz keeps it in the unpacked folder.
Is there an official DBeaver troubleshooting page?
Not a single index of common failures. DBeaver Corp publishes product documentation, and real-world problems are worked out in the GitHub issue tracker. That gap is why this page exists — and why anything here that comes from the tracker rather than the docs is labelled as such.
Written by Clarence N. Adams, Editor, Unofficial DBeaver Guide · updated · unofficial; mechanical fixes are reproducible on your own machine, and community-reported behaviour is labelled where it appears. Something missing or wrong? [email protected].