1# Troubleshooting23Start with:45```sh6deno task doctor7```89The report names the blocked capability or configuration and gives a remediation without printing10environment values.1112## Doctor or build reports a PWA source blocker1314Start with the first named file and action. The checks validate `public/manifest.webmanifest` as15JSON; require stable identity, names, same-origin launch scope, display mode, colors, and complete16icon roles; and inspect the dimensions and MIME types of local icons, shortcuts, and optional17screenshots. Asset filenames and branding are replaceable, and unknown optional manifest members18remain allowed.1920If source checks pass but build reports `dist/`, do not hand-edit the output. Fix the author-owned21manifest, shell link, route, or asset, then rerun `deno task build`. The production check22deliberately treats HTML manifest links, the worker revision and scope, `lofi-build.json`, and23`lofi-precache.json` as one artifact so a partial or stale build cannot pass.2425## The app says configuration is incomplete2627Managed sync requires both public values:2829```text30JAZZ_APP_ID31JAZZ_SERVER_URL32```3334Set both, or remove both to run local-only. Do not move `JAZZ_ADMIN_SECRET` or `BACKEND_SECRET` into35client-visible variables.3637If provisioning should replace an existing `.env`, review and back up the intended configuration,38then use the command's explicit `--force` option:3940```sh41deno task jazz:provision --force42```4344## Durable storage is blocked4546lofi requires a secure context, OPFS, SharedWorker, Web Locks, and MessageChannel. It stops instead47of silently switching to memory-only data.4849- Use a supported browser: Android Chrome 148+ or iOS Safari 16.4+.50- Use `localhost` during development or HTTPS on another device.51- Avoid embedded/private browser surfaces that disable required storage APIs.52- Treat clearing site data as destructive unless the account has synced and the recovery phrase is53 safe.5455## Another tab is running an incompatible app version5657Lofi stops persistent runtime startup when another tab for the same app is using an incompatible58browser broker configuration. This is reported as `broker-incompatible` in runtime diagnostics in59both local and managed mode.60611. Close every other tab or installed-app window for this app.622. Return to the tab showing the recovery notice.633. Select **Reload app** once.6465The package does not take over the existing broker, fall back to memory, or automatically enter a66reload loop. Do not clear site data for this condition: closing the incompatible tabs and explicitly67reloading creates the clean document boundary the persistent driver requires.6869## A task disappeared after changing app configuration7071Check whether `databaseName` or the managed `JAZZ_APP_ID` changed. Both participate in the durable72storage namespace. Restoring the old values reopens the old namespace; copying rows between73namespaces is not automatic.7475## Preview says the build is missing or stale7677Run:7879```sh80deno task build81deno task preview82```8384Do not hand-create `dist/lofi-build.json`; it must describe the output produced by the build.8586## The production build reports a secret leak8788Remove the named server-only value from source, public files, logs, fixtures, and generated client89configuration. Rotate a real credential if it entered source control or an artifact, then rebuild.9091## Browser tests skip or cannot launch9293Set the base URL when running the opt-in example:9495```sh96LOFI_E2E_BASE_URL=http://127.0.0.1:4321/ \97 deno test -A tests/convergence_e2e_test.ts98```99100Install the pinned Chromium runtime if needed:101102```sh103deno run -A npm:playwright@1.61.1 install chromium104```105106## Local writes work but another device does not update107108Check these states separately:1091101. The deployment has a complete public Jazz pair.1112. The user explicitly elected to sync in `AccountGate`.1123. The latest write reached global durability rather than only local durability.1134. Both devices restored the same account identity.1145. The deployed schema and permissions allow the operation.115116“Sync configured” is not proof that a specific user opted in or that a specific write reached the117server.118119## A device with an enrolled ticket came back local-only120121The declared sync location persists as a sealed record whose key lives in the browser's IndexedDB.122Clearing site data partially — IndexedDB without localStorage, or a browser "free up space" eviction123— leaves the record in place but unopenable, and the device deliberately falls back to local-only124rather than guessing. Local data is untouched. Re-enroll the ticket (paste it again) to declare the125sink and resume syncing under the same account.126127## Recovery does not restore a recent item128129The phrase restores account authority, not unsynced device storage. Data returns only if it reached130managed sync before the original device was lost or cleared.131132## Passkey restore was cancelled or cannot find an account133134- **Cancelled:** retry the user-verification prompt, or continue with the recovery phrase.135- **No recoverable passkey:** confirm the passkey exists in the active provider. A legacy136 phrase-reveal guard is not an account backup.137- **Different app hostname / RP-ID:** open the canonical production hostname used during backup.138- **Verification failed:** unlock the platform/password-manager authenticator and retry.139- **Unsupported browser/provider:** use the recovery phrase. Provider availability is not portable140 across every iOS, Android, browser, and password-manager combination.141142The package maps these states without printing credential IDs, account secrets, or phrases.143144## Sharing says managed sync is required145146Private resources work local-only. Direct shares and groups require both a configured Jazz server147and the current account's explicit sync election. Back up and enable sync in `AccountGate`, then148retry. A configured deployment alone does not opt the current account into sync.