Local database corruption is not recoverable / "no backend registered" errors with empty inboxes

Open
#249 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
playwright, sqlite, typescript

Research direction

Start with src/db/shared-worker.ts and src/db/bootstrap-idb.ts to trace how boot failures are cached, then read src/stores/auth-store.ts and src/sync/sync-client.ts for error handling and backend lookup. Check AGENTS.md for the Playwright test setup and inspect the related pull request #227. Done means a corrupted cache can recover and resync, with typed errors and coverage for that flow.

Written by the indexing model from the issue text.

Description

Describe the bug

The browser keeps a disposable SQLite cache (wa-sqlite on IndexedDB, in a SharedWorker), and the UI reads only from that cache. Corruption of the local copy therefore leaves the app unusable even though the server data is intact.

Findings from reading the code
  • No corruption handling. Nothing in src/db, src/stores or src/sync handles SQLITE_CORRUPT/NOTADB or deletes and rebuilds stormbox.sqlite. The only recovery currently is for the user to clear site data by hand.
  • Boot failure is cached forever. getHandlers() (src/db/shared-worker.ts) and bootProductionEngine() (src/db/bootstrap-idb.ts) keep a rejected promise. After one failed boot, every RPC from every tab fails until the worker dies, and startSyncAccount never registers a backend.
  • Raw error shown. reportDatabaseError (src/stores/auth-store.ts) only recognises DatabaseUnavailableError, which is created only for the Firefox startup timeout. A corruption error is shown as its raw message, with no recovery steps.
  • "No backend registered" message. It comes from SyncClient.getBackend (src/sync/sync-client.ts:62) as a plain Error, not the typed accountUnavailable used elsewhere in sync-host.ts. It occurs when a tab holds an accountId but the worker's backend map has no entry for it, for example after a worker restart or replacement without the tab reloading.
  • Suspected trigger, not confirmed. The corruption may relate to the Firefox exclusive-locking and journal change (#228), or the wa-sqlite 2.0.9 upgrade (#229), acting on a database written by an earlier build. Mixed asset versions across tabs could also contribute.

Related: https://github.com/thunderbird/stormbox/pull/227

To Reproduce

  1. Boot failure is cached. In a profile with Webmail signed in, corrupt the stormbox.sqlite IndexedDB data (for example, overwrite a block through DevTools) and reload.
    • Expected from the code: the raw "malformed" message appears, and a reload without closing all tabs does not recover.
  2. "No backend" message. With Stormbox signed in, cause the SharedWorker to be replaced without the tab reloading. Examples are a Firefox handoff via a second tab on a different build, or killing the worker from about:debugging or chrome://inspect/#workers.
    • Check whether the original tab shows empty inboxes and "No jmap-mail backend registered for account N".
  3. Affected users. Ask for browser and version, whether the database predates Oct 26, whether several tabs were open, and the console output. Look for [worker:sync-host] startAccount complete and any shared-worker boot or restart warnings.
  4. Clearing site data. Check that it fixes both reports. If it does, that confirms the cache is the cause.

Expected behavior

Corrupted databases should hopefully have a path for self-heal. This is a proposed fix (not implemented):

  1. On SQLITE_CORRUPT/NOTADB during open or migrations, delete the IndexedDB database and boot once more.
  2. Don't cache a rejected boot promise.
  3. Map corruption to a typed UI error with recovery instructions.
  4. Make getBackend throw the typed accountUnavailable error, and have the store re-run startSyncAccount on it.
  5. Add Playwright coverage (per AGENTS.md) for a corrupted database recovering and resyncing.

Actual behavior

Empty mailbox with a database error per screenshot below.

Screenshots

Image

System

  • OS: macOS Tahoe 26.6.2
  • Browser Version: Firefox 158.0
Dominant language
TypeScript
Stars
121
Forks
11
Avg merge
1d 3h
Merged PRs (30d)
11

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from thunderbird/stormbox

All issues in thunderbird/stormbox

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.