Diagnosing offline + install issues

For teachersFor parentsFor studentsFor adminsFor public· 2 min read

How to read the /diagnostics/pwa screen — service worker state, cache state, install state — and what to screenshot when reporting an issue.

The diagnostics screen at /diagnostics/pwa is the device-side view of how the PWA is set up — service worker status, cache buckets, install state, network. Use it when:

Bookmarked content won't open offline.
The install prompt never appeared.
"Update available" loops or won't apply.
Support asks "what's your SW state?"

Open via Settings → About → PWA diagnostics, or browse to /diagnostics/pwa directly. The page works offline (it's in the precache).

What each card means

Browser

User-Agent, Display mode (standalone), and language. "Yes (installed PWA)" means you're running the installed app; "No (browser tab)" means a normal tab.

Service worker

A Healthy / Issue chip plus seven rows: Supported, Registered, Scope, Active script, Controller state, Updating, Waiting. If the worker exists but isn't yet controlling the page, the note tells you to reload the page yourself, then tap Re-check.

Caches

Reads the Cache Storage API and tallies:

Storage available — whether the Cache API is callable at all. Some private modes disable it.
Cache buckets — number of named caches (one per Workbox rule + a precache).
Total entries — sum of cached responses across all buckets, with a per-bucket entry-count table.
/offline page cached — the fallback page Workbox serves when navigation falls through. Critical for the offline experience.

If the caches are empty, the note explains what to do (reload while online once, then wait ~10 seconds for the precache to populate).

Network

navigator.onLine, the connection's effective type, downlink, and Save-Data.

Reporting an issue

If you're stuck and need to email support, screenshot the whole diagnostics page and attach. Include:

Device + browser version (Settings → About → Build info has these).
What you were trying to do.
The diagnostics page itself — it's the single screenshot that tells us where the problem is without 20 back-and-forth emails.

Email hello@keybaki.com with PWA diagnostics in the subject line.

Common issues

"Active but not controlling" never goes away. Some browsers (especially Brave / Firefox with privacy add-ons) sandbox the SW so it never claims the page. Forcing reload (Ctrl/Cmd-Shift-R) usually works; otherwise the app still functions, just without offline.
Storage available: No. You're in private / incognito mode. Switch to a normal window.
Total entries: 0. SW registered but hasn't precached yet. Stay online for 10 seconds with the page open — Workbox runs the precache then.
/offline not cached. The precache list missed it. This is a build-time issue we should know about — email us the diagnostics screenshot.
iOS Safari "Standalone: No" after adding to home screen. iOS sometimes opens the bookmark in Safari instead of the standalone shell. Long-press the home-screen icon → confirm it says "App" and not "Bookmark". If it says Bookmark, delete + re-add.