Recover a corrupt WhatsApp database (msgstore.db)

A WhatsApp database is an ordinary SQLite file, so it's a flat array of fixed-size pages (SQLite's default is often 4 KB). The very first 16 bytes are the magic string SQLite format 3\0; the rest of page 1 holds the file header and the sqlite_schema that lists every table. Each table is a b-tree: interior pages carry pointers down to leaf pages, and the leaf pages hold your actual rows.

The tables that matter for chat history are predictable. Modern WhatsApp builds keep messages in a message table (older builds used messages), the conversation list in chat, and the phone-number/group identifiers in jid. Message text lives in a text column (text_data on the modern schema, data on the legacy one), and every row carries a timestamp in Unix epoch milliseconds. Supporting tables like message_media, message_thumbnail, message_quoted and call_log round it out. Crucially, the photos, videos and voice notes themselves are not in the database — those are separate files in the WhatsApp Media folder; the DB only stores their file paths plus small thumbnails.

WhatsApp runs the database in WAL (write-ahead logging) mode, so on the phone you'll see two sibling files next to it: msgstore.db-wal and msgstore.db-shm. Recent, committed messages can live only in the -wal file until they're checkpointed back into the main .db. If you have that sidecar, keep it — its committed frames are the newest rows.

SQLite raises SQLITE_CORRUPT (result code 11) — surfaced as "database disk image is malformed" — the moment it follows a pointer and lands on something that isn't a valid b-tree page: a zeroed page, a bad cell offset, a page count that disagrees with the file size. It stops at the first inconsistency, which is why one damaged interior page takes the whole file down while the untouched leaf pages behind it still hold your messages. A related error, "file is not a database," means the 16-byte header magic itself was mangled — the pages behind it are often fine.

The damage usually comes from an interrupted write. Pulling msgstore.db off a phone over USB or through a file manager while WhatsApp still has it open can copy a torn, half-checkpointed file; a byte flip on a failing SD card or in a sync, or a device that lost power mid-write, does the same. A truncated copy simply loses whatever pages were at the tail.

One trap catches people first: the file in WhatsApp's backup folder is not a plain database. Backups are named msgstore.db.crypt14 or msgstore.db.crypt15 and are AES-GCM encrypted (the key sits at /data/data/com.whatsapp/files/key, or, for crypt15, behind your end-to-end backup password). A .crypt14/.crypt15 file reads as high-entropy noise — it has no SQLite header at all, so page recovery can't touch it until it's decrypted back to a plain msgstore.db. This tool works on the decrypted database, not the encrypted backup.

Instead of trusting the broken pointers, the tool reads the file page by page: it reconstructs the schema, walks each table's b-tree, and for anything the pointer chain can no longer reach it falls back to a raw page sweep that decodes the self-describing records straight out of the leaf pages. It rebuilds the b-trees from scratch around the rows it finds and writes them into a brand-new database you download — the same strategy as SQLite's own .recover command. Rows that can't be attributed to a known table are placed in a lost_and_found table rather than discarded, and if you supply the msgstore.db-wal sidecar its committed frames are overlaid first so the result reflects your last committed messages, not just the last checkpoint.

The honest limits: bytes that were physically overwritten or truncated off the end are gone, and no tool can invent them. Values come back as their on-disk storage class, so a column's affinity may shift. Because the sweep also reads freelist and unvacuumed pages, some previously-deleted messages can resurface. Recovered data is always suspect — SQLite's own docs say so — so verify it against a known-good source before relying on it. And the media blobs still live in the separate Media folder; the database gives you the text and the references, not the pictures themselves.

Why do this in the browser? A chat database is the single worst file to hand to a server you don't control — it can hold every message, phone number and timestamp you've ever exchanged. Upload-based "repair" tools copy that file onto infrastructure you can't inspect, under retention terms you didn't write. Here the file is read from your disk and rebuilt in your tab; you can open the Network panel and confirm 0 bytes of the database leave your machine.