KakuremiTroubleshooting: Vault Won't Open on Your Mac (iCloud Placeholder Files)
You keep one .kdbx vault and open it both in Kakuremi on your iPhone and in a desktop KeePass app on your Mac. One day the Mac app reports a database read error — yet the very same vault still opens fine in Kakuremi. In almost every case the file is not corrupted: your Mac is holding an empty placeholder of it. This guide shows how to confirm that and fix it in minutes.
Read the error message precisely
Desktop KeePass apps distinguish two very different failures, and the wording tells you which one you have. In KeePassXC, for example:
"Failed to read database file." — the app could not get the file's bytes at all. This is the placeholder problem this guide solves. Keep reading.
"Error while reading the database: Invalid credentials were provided" / "HMAC mismatch" — the file reads fine; the master password, key file, or hardware key is wrong. That is a different problem — recheck your credentials.
Why this happens: placeholder files
To free disk space, macOS can quietly replace a rarely-opened local file with a placeholder (Apple calls this Optimize Mac Storage; third-party sync clients have similar "files on demand" features). Finder still shows the file name and its full size, but the content lives only in the cloud.
Normally, opening a placeholder re-downloads it automatically. But that silent re-download can fail to fire — and then every app that tries to read the raw file, including any desktop KeePass app, sees an unreadable, empty file.
Your iPhone is unaffected because it kept its own fully-downloaded copy — which is exactly why Kakuremi still opens the vault while your Mac cannot.
The fix: force the file to download
In Finder, right-click the .kdbx file and choose Download Now (files stored in iCloud show a cloud icon next to them). When the cloud icon disappears, retry your desktop app.
If Finder doesn't offer the option, or you prefer the Terminal:
brctl download ~/Documents/path/to/vault.kdbx
Give it a few seconds, then verify with ls -lO vault.kdbx — the dataless flag in the output should be gone. The vault now opens normally.
brctl works for files managed by iCloud Drive. If the folder is managed by a third-party sync client instead, use that client's own "download" / "available offline" action — see the next step to find out which one owns the file.Still failing? Find out which service manages the folder
Folder names can mislead. With iCloud's Desktop & Documents sync enabled, everything under ~/Documents and ~/Desktop is managed by iCloud — even a folder that carries the name of another sync tool you used years ago.
To see which provider really owns the file, run:
fileproviderctl evaluate ~/Documents/path/to/vault.kdbx
Output mentioning Ubiquitous… means iCloud — use Finder or brctl as in Step 3. If a third-party provider is named instead, make sure that client is installed, running, and signed in; a placeholder whose sync client was uninstalled stays unreadable until the client is restored (or you fetch the file from that service directly).
Prevent it from happening again
In Finder, right-click the vault (or its folder) and choose Keep Downloaded. macOS will stop evicting it, so desktop apps always have real bytes to read.
Alternatively, turn off System Settings → Apple ID → iCloud → Optimize Mac Storage — at the cost of more disk usage for all iCloud files.
Keep one sync service per vault. Two clients syncing the same folder make it hard to tell who owns the file — and invite the silent-overwrite conflicts described in the iCloud Drive guide.
.kdbx hasn't been downloaded there, Kakuremi reports error KR-3005 (file unreadable). Fix it the same way — open the Files app, tap the file to download it, then retry. And as always: edit on one device at a time, because the last save wins.