You double-click KeePassXC and nothing. Or a window flashes and vanishes. Or the app opens fine but your .kdbx refuses to, and the database is the thing that is “not opening”. The three complaints get the same search query and completely different fixes — so start by naming which one you have.
Triage: what does “not opening” look like?
| Symptom | What is actually broken | Go to |
|---|---|---|
| No window at all, no error | A stale process or a blocked start | Causes 1, 3 |
| Window appears, then closes immediately | Startup crash — config or runtime | Causes 2, 7 |
| App opens, but the database will not | The file, its lock, or its sync copy | Causes 4, 5, 8 |
| “The database file is already open” | A stale lock file | Cause 4 |
| Key file or YubiKey prompt never appears | Hardware key not detected | Cause 6 |
1. A stale KeePassXC process is holding everything
The most common cause on Windows, and the fastest to fix: a previous KeePassXC window closed but its process kept running — invisible, holding the database lock and the single-instance mutex. Every new double-click signals the hidden process and does nothing visible.
- Windows: open Task Manager (Ctrl+Shift+Esc), look under both Apps and Background processes for KeePassXC, and End task each one. Then launch normally.
- From a terminal:
taskkill /IM keepassxc.exe /Fon Windows,pkill keepassxcon Linux. - If it happens repeatedly, check whether your session manager kills the window but not the process on logoff — and close KeePassXC from its menu rather than the X button before locking the screen.
2. The configuration file is corrupt
KeePassXC stores its settings in one small file — keepassxc.ini in the per-user config directory (%APPDATA%\KeePassXC on Windows, ~/.config/KeePassXC on Linux, the app support folder under ~/Library on macOS), plus keepassxc_local.ini beside the executable in portable installs. A crash during a settings write can leave it unreadable, and the app exits silently at startup.
The fix is safe: close KeePassXC fully (cause 1), rename the file to keepassxc.ini.bak, and launch. The app rebuilds defaults on first run. Your passwords are not in this file — the database is a separate .kdbx, and nothing about it changes. You re-apply preferences afterwards.
3. Security software blocks the start
Antivirus and endpoint products react to a password manager doing password-manager things — reading key files, injecting into browsers for autofill — and Controlled Folder Access on Windows is a repeat offender. The symptom is a start that dies with no error, or a Defender notification you swiped away.
- Windows: Windows Security → Virus & threat protection → Protection history — look for a blocked KeePassXC action. If Controlled Folder Access is on, add KeePassXC under Allow an app through Controlled Folder Access.
- macOS: a dialog about the app not being from an identified developer is Gatekeeper quarantine. Clear it with
xattr -dr com.apple.quarantine /Applications/KeePassXC.appor approve it under System Settings → Privacy & Security. - Downloaded installer leftovers: on Windows, files pulled from the web carry a block attribute — right-click the executable → Properties → Unblock.
4. A stale lock file says the database is already open
KeePassXC drops a hidden lock file next to the database while it is open. After a crash or a forced kill, the lock stays behind — and the next open is refused with “the database file is already open”, even though no instance is running.
Make sure KeePassXC is truly closed (cause 1), then delete the hidden lock file beside your database — its name starts with a tilde or dot and ends in .lock, in the same folder as the .kdbx. Deleting it is safe when no instance holds the database; it contains no password data.
5. The cloud-synced copy is the problem
If the database lives in OneDrive, Dropbox, Google Drive or a network share, the sync client is a suspect in its own right:
- Conflicted copies. Two devices editing the same database produce
name (conflicted copy).kdbxfiles. You may be opening the stale one, or the sync is busy writing while KeePassXC reads. Decide which copy is current — by its modification time and your recent edits — keep it as the database, and archive the others. - Placeholder files. OneDrive’s online-only mode serves a stub, not the database. Force Always keep on this device on the
.kdbx. - The lock goes missing. Sync clients can delete or duplicate lock files. If the database is shared between machines, only one machine should open it at a time — that is a format constraint, not a setting.
6. YubiKey or hardware key is not detected
If the database uses a YubiKey challenge-response or a hardware key, and the prompt never appears (or the key is rejected):
- Re-insert the key — directly into the machine, not a hub — after KeePassXC is open.
- Close anything else that may hold the key: YubiKey Manager, a browser using it for2FA, another KeePassXC instance.
- Confirm the key works at all in YubiKey Manager, and that the configured slot still has the challenge-response secret (slot 2 is the KeePassXC convention).
- Try another USB port and, on Windows, let the driver settle for a few seconds after inserting.
7. The install is damaged or missing a runtime
After an upgrade or an interrupted install, the app can fail before any window appears. Windows builds need the Visual C++ runtime; Flatpak/Snap/AppImage builds need their own plumbing (FUSE for AppImage); and a macOS “not supported on this Mac” message means the build requires a newer OS than this one.
Reinstall the current version from keepassxc.org/download over the existing one — it keeps settings and databases. On Linux, prefer your distribution’s package or the AppImage; if the AppImage will not start, check that FUSE is installed before blaming the app.
8. The database file is gone from where it was
The app opens, the file dialog remembers the old path, and nothing loads: the database moved, its drive is unplugged, a sync client renamed it, or permissions changed after an OS update. This looks identical to “KeePassXC not opening” in every search bar.
Use Database → Open Database and browse to the file’s real location rather than the recent-files entry. If you cannot find the file at all, search the whole disk for *.kdbx — it is usually somewhere obvious with a conflicted or renamed copy nearby.
Confirm the fix
| Test | Expected result |
|---|---|
| Launch with no database configured | The main window appears and stays |
| Create a new empty database, save, close, reopen it | Opens without error — proves the app is healthy |
| Open the real database | Key-file / YubiKey prompt appears and accepts |
| Reopen after a normal close | No “already open” complaint (lock clean) |
The second row is the fork: if a brand-new database will not open, the problem is the app or its environment (causes 1–3, 7); if only the real database fails, the problem is the file or its accessories (causes 4–6, 8).
Frequently asked questions
KeePassXC not opening on Windows 11 — what is the first thing to try?
End every KeePassXC process in Task Manager and launch again. A stale background process is the single most common cause. If it happens again on every close, move on to renaming the configuration file — both fixes take under a minute and touch nothing that stores passwords.
Will renaming the configuration file delete my passwords?
No. The configuration file stores preferences — window layout, clipboard timeout, autofill settings. Your passwords live in the .kdbx database, which is untouched. You will need to re-apply a few preferences after the reset.
Why does KeePassXC say the database is already open?
A lock file beside the database says an instance has it open. After a crash that lock can be stale. Confirm no KeePassXC process is running, delete the hidden lock file next to the .kdbx, and open again.
KeePassXC is not detecting my YubiKey. What should I check?
Re-insert it directly into the machine after the app is open, close other software that uses the key (YubiKey Manager, browser 2FA), and verify the key in YubiKey Manager. If the database expects challenge-response, the configured slot must still hold that secret.
What does “not supported on this Mac” mean?
Two different things, one dialog: either the app is quarantined by Gatekeeper (fix with xattr -dr com.apple.quarantine or Privacy & Security approval) or this macOS version is older than the build requires. Check the release notes for the minimum OS before reinstalling.
See also: KeePassXC Database Corrupt or "File Read Error" — when the app opens but the .kdbx will not.
See also: KeePassXC Database Corrupt or "File Read Error" — when the app opens but the .kdbx will not.