Skip to content

Troubleshooting

Common problems and how to fix them, grouped by area.

Builds and deploys

The Pages build fails. Open the failed deployment's build log in the Pages dashboard and read the first red error.

  • Make sure Build command is npm run build and Build output directory is client/dist.
  • A tsc / TypeScript error means the code doesn't compile — run npm run build locally to reproduce and fix it, then push again.

The site loads but shows a blank page or 404s on refresh. Confirm Build output directory is client/dist. Pages serves the single-page app from there.

Database

Screens error or show no data; the API returns 500. The remote database probably has no tables. Run:

npm run db:migrate:remote

wrangler says it can't find the database / wrong ID. Check that database_id in wrangler.toml matches an existing database. List them with npx wrangler d1 list. Re-run npx wrangler login if you're not authenticated.

A new feature errors about a missing column. A migration wasn't applied. Run npm run db:migrate:remote (and :local for your machine). For example, the "who changed it" history feature needs migration 0010_snapshot_created_by.sql.

Local and remote behave differently. They're separate databases. Apply migrations to both (db:migrate:local and db:migrate:remote). Never edit an already-applied migration file — add a new numbered one.

Sign-in and roles

Visiting the app doesn't ask me to sign in. The Cloudflare Access policy isn't covering the domain. In Zero Trust → Access → Applications, confirm an application exists for oncall.totlcom.com with an Allow policy. Test in a private window.

/api/v1/me shows email: "unknown". Cloudflare Access isn't in front of that request, or the token isn't reaching the app. Confirm the Access application's domain exactly matches oncall.totlcom.com and that you reached the app through the sign-in (not a preview *.pages.dev URL that isn't covered by the policy).

No one is an admin / the Admin tab is missing. ADMIN_EMAILS isn't set in production, or doesn't include your address. Set it in Pages → Settings → Variables and secrets (Environment variables), then redeploy. Your email there must match your Microsoft sign-in email exactly.

Microsoft sign-in fails or loops. - The client secret may have expired — create a new one in Entra ID and update it in Zero Trust → Settings → Authentication. - Check the Redirect URI in the Entra app exactly matches https://<team>.cloudflareaccess.com/cdn-cgi/access/callback. - Make sure admin consent was granted for the API permissions.

A user can sign in but shouldn't be able to. Access (who can sign in) is separate from app roles (what they can do). Remove them from the Access policy to block sign-in entirely; set them to Viewer in the Admin tab to merely remove editing.

Docs site

mkdocs: command not found. Install the packages first: pip install -r requirements.txt from the docs-site folder. On macOS try pip3.

Docs site shows "Not Found" after upload. You uploaded the site folder instead of its contents. Re-upload so index.html is at the top level. See Deploy this docs site.

Docs don't ask for sign-in. Add a Cloudflare Access application + policy for docs.oncall.totlcom.com (Part 4).

Still stuck?

Capture the exact error text (and the build log if it's a deploy issue) before asking for help — it almost always points straight at the cause.