Why do I see 'file is not a database'?

Usually because the encryption key is wrong or SQLCipher parameters (version, kdf_iter, page size) don't match the file. Verify the key and open with the same SQLCipher version used to create the DB.

How do I know if my file is encrypted?

Encrypted SQLCipher files don't start with the 'SQLite format 3' header. If the DB opens only after entering a key, it's encrypted. You can also verify in DB Browser by running PRAGMA cipher_version; after opening.

I entered the correct key but it still fails.

There may be a SQLCipher version mismatch (e.g., v3 vs v4) or different kdf_iter/page_size. Try opening in the tool that created it, then export/import to migrate to your environment.

What's the safest way to rekey or migrate?

Always back up first. Open the DB with the working tool, export to SQL, then import into a new encrypted DB using your desired settings.

Troubleshooting SQLCipher on Windows — Fix “file is not a database”

Practical fixes • SQLCipher on Windows

Troubleshooting: SQLCipher Errors and Fixes

Solve common errors in DB Browser (SQLCipher) for Windows: “file is not a database”, wrong key, version mismatches (v3 vs v4), kdf_iter and page size differences, HMAC and integrity check failures.

Download Portable (v3.13.1) Security best practices Migrate / Convert

Diagnose the problem

Is the file encrypted?

Encrypted SQLCipher files do not start with the plain SQLite header. If the DB only opens with a key, it's encrypted. After opening, run PRAGMA cipher_version; to verify encryption support.

Key vs parameters

A correct key with wrong parameters can fail. Version (v3/v4), kdf_iter, and page size must match how the DB was created.

Source environment

Open the DB with the original app/tool if possible, then export/import to migrate to your current build.

Fix “file is not a database”

Confirm the key — retype carefully and check keyboard layout and trailing spaces.
Match SQLCipher version — determine if the DB was created with v3 or v4; open with a compatible build.
Align parameters — if advanced options are exposed, match kdf_iter and page_size. Otherwise, open in the original tool and export/import.
Test integrity after opening — run PRAGMA cipher_integrity_check;. If issues persist, export to SQL and re-import.

Still stuck? See FAQ below, or jump to Migrate for safe conversion paths.

Other common errors

Wrong key or HMAC mismatch — ensure the passphrase is correct; version/parameter mismatches may cause HMAC failures.
“database disk image is malformed” — indicates corruption. If you can open, export to SQL, then import into a fresh DB.
“no such table” after opening — may indicate the DB wasn’t actually decrypted. Verify with PRAGMA cipher_version; and re-open with correct settings.
Slow open — high kdf_iter values increase key derivation time. This is expected for stronger security.

Prevent issues

Back up before rekeying or migrating.
Document SQLCipher version and parameters used for the project.
Use long, unique passphrases.
Keep your tools updated and consistent across environments.

Security best practices Encrypt / Decrypt guide

FAQ

How can I tell if a database is encrypted?

Encrypted files lack the 'SQLite format 3\u0000' header. In practice, if opening requires a key and succeeds only with the right key, it’s encrypted. After opening, verify with PRAGMA cipher_version;.

What’s the difference between SQLCipher v3 and v4?

They use different defaults (e.g., HMAC, page size, KDF iterations). A DB created with v3 may not open with v4 defaults and vice versa. Use matching settings or migrate via export/import.

I forgot the passphrase. Can I recover my data?

If the key is lost, SQLCipher encryption cannot be bypassed. Without the correct key and parameters, recovery is not feasible.

After opening, I see garbled data.

This often indicates decryption didn’t occur (wrong parameters) or corruption. Reopen with correct settings, then export/import to a new DB.

Page last modified: --

Canonical: https://db-browser.github.io/troubleshooting-sqlcipher.html