KeePassXC Database Corrupt or "File Read Error": 6 Causes, in Order

KeePassXC opens but the .kdbx will not — "file read error", "database corrupt", "not connected". Six causes in order, from sync copies and lost key files to…

The app starts fine — it is the database that will not open. KeePassXC reports a file read error, calls the database corrupt, or silently fails to load it. Before concluding the file is dead: in most reported cases it is not corruption at all. It is a sync copy, a moved key file, or a stale lock.

Six causes, in the order they actually occur. (If the app itself never opens, that is a different list: KeePassXC Not Opening: 8 Causes.)

Triage: what exactly does the error say?

Message or symptomWhat it usually isGo to
"Error while reading the database: file read error" / cannot open fileThe path points at a stub, a moved file, or an unreadable locationCauses 1, 6
"Invalid key" / "wrong master key" — but it always workedA key file or YubiKey slot changed underneath the databaseCause 2
"The database file is already open"A stale lock file from a crashCause 3
Opens on one machine, fails on anotherDifferent copies of the file — sync conflictsCause 1
Error mentions corruption / checksum after a crash or power lossInterrupted write — genuine damage is possibleCauses 4–5
Created by a newer KeePassXC, opened by an older oneFormat capability mismatchCause 6

1. You are opening the wrong copy (sync conflicts and placeholders)

The single most common "corrupt database" report is not about the file at all. When the .kdbx lives in OneDrive, Dropbox, Google Drive or a network share:

  • Placeholder files. OneDrive's online-only mode serves a stub. KeePassXC reads a few bytes, and reports a read error. Force Always keep on this device and open again.
  • Conflicted copies. Two devices editing the same database produce name (conflicted copy).kdbx files. You may be opening a truncated sibling while the real database sits beside it. List the folder by modification time: the copy with the most recent real edit wins; archive the rest.
  • Network-share paths. The KeePassXC maintainers' own long-standing advice: keep the working copy on a local disk and copy to the network location afterwards — network drives are the most-reported source of save corruption.

The same sync machinery causes Bitwarden headaches — the sibling guide: Bitwarden Not Syncing.

2. The key file moved, or the YubiKey slot changed ("Invalid key")

A KeePassXC database can have three key components: the master password, a key file, and/or a hardware key challenge-response. If any component changed, the database looks locked or broken:

  • Key file path. The database remembers where the key file was. After a move or re-image the dialog silently reverts to "none" — or points at the wrong file. Use Database → Open database, and in the key-provider dialog browse explicitly to the key file's current location.
  • YubiKey slot. The challenge-response secret lives in a slot (slot 2 by convention). A firmware reset, a different YubiKey, or a re-programmed slot = a different key. Confirm the slot still holds the response in YubiKey Manager.
  • Composite key in general. If a colleague set up "password + key file" and sent you only the password, the database is not corrupt — it is simply not fully keyed for you.

This cause is easy to miss because the error blames the file. It is the key.

3. A stale lock file says the database is already open

KeePassXC drops a hidden lock file (a name starting with ~ or ., ending .lock) next to the database while it is open. After a crash it stays behind and blocks the next open. Close KeePassXC fully (including a hidden process — see cause 1 of the app guide), delete the lock file, open again. The lock file contains no password data; deleting it while no instance is running is safe.

4. An interrupted write left a truncated file

If the failure arrived together with a crash, a forced shutdown, a full disk, or the machine dying mid-save, the last write may have stopped partway. KeePassXC writes carefully, but no writer survives a cut power line every time:

  • Do not keep pressing save. Every attempted save over the damaged file destroys more of it.
  • Copy the file aside first — work on the copy from here on.
  • Then try recovery in the next section.

5. Real corruption (disk, USB, network) — and how to recover

Actual damage happens — most often on USB sticks removed without unmounting, failing disks, and network shares. Recovery, in order of hopefulness:

  1. KeePassXC's backup folder. If "save backup" was enabled (Database settings), earlier .kdbx versions sit in the backup directory beside the database. Open the newest one that works.
  2. File history. Windows File History, macOS Time Machine, and the cloud providers' own version history (right-click the file on the web UI → version history) routinely hold a good copy from hours earlier.
  3. Other devices. Any machine that has not synced since the damage still holds the good copy. Disconnect it from sync first.
  4. Damage check. The maintainers' diagnostic trick: hash the file before and after copying it (sha256sum database.kdbx on both ends). Different hashes = the storage layer is corrupting bytes — the database may never have been the problem.

What not to do: no online "kdbx repair" services (you would be uploading your vault), no random repair tools from forum links, and no typing the master password anywhere except KeePassXC itself. If nothing recovers it, the painful lesson is the standard one: a password vault needs its own backup — managers make this practical, but only a backup makes it survivable.

6. Version and format mismatch

A database saved by a current KeePassXC uses capabilities older versions do not understand — an old install then reports a read error or refuses the file. And the reverse: a very old database in a legacy format may need one-time upgrade. Install the current version from keepassxc.org/download on the machine that fails; installing over the existing app keeps settings and does not touch the database.

Confirm the fix

StepExpected result
Open the copy you intend to, by explicit pathKey prompt appears — that alone proves the header is readable
Unlock with the full composite key (password + key file / YubiKey)Database opens; groups load
Make a trivial change and save; reopenRound-trips cleanly — the file is healthy going forward

Frequently asked questions

Can a corrupted KeePassXC database be recovered?

Often yes — from the backup folder, file or cloud version history, or another device that has not synced the damage. Those first; only then consider the file truly lost. Never hand a vault to an online repair service.

Why does KeePassXC say "file read error"?

Usually the file at that path is not the complete database: a cloud placeholder stub, a conflicted sibling, a moved file, or permissions changed after an OS update. Open by explicit path, from local storage, before suspecting damage.

How do I tell whether my kdbx is actually corrupt?

Try opening a copy on a different machine or a different KeePassXC version. If it opens elsewhere, the problem is the environment (sync, key file, version). If the key prompt appears but the key never unlocks, the database is readable and the key inputs are wrong — cause 2.

Does KeePassXC keep automatic backups?

Only if backup saving is enabled in the database settings — it keeps prior versions in a backup folder beside the database. Check that setting now, before you need it; combine it with any file-history or cloud-versioning you already have.

Is my data safe if the file is corrupted?

The master key is not stored in the file, and corruption does not leak contents — the database is encrypted end to end. Corruption risks availability, not confidentiality. What puts data at risk is uploading the vault somewhere to "fix" it.


Keep reading

Related articles

Browse all articles