Skip to main content

Validation & Troubleshooting

Use this page to answer two questions:

  1. "Is it actually working?" — the smoke tests to run after a deploy or a local change.
  2. "It's broken — where do I look?" — a symptom-first runbook.

The checks target the current Firebase-hosted / Azure-backed setup. They stay useful as reference through the AWS migration — the what to verify doesn't change even when the where does.

Post-deploy smoke test​

Run this right after npm run deploy or npm run deploy:app. Open the deployed site (see the target → site map in Deployment) and confirm, in order:

  • Page loads — no blank screen, no build/asset 404s in the console.
  • Login works — email/password, and at least one SSO (Google / Microsoft).
  • Dashboard renders — cards and the trend graph show data (not spinners or empty states).
  • API is reachable — Network tab shows .../api/user/... calls returning 200 (not 401/500/CORS errors).
  • Real-time — the WebSocket connection is established (Network → WS tab shows a live wss://...webpubsub.azure.com socket).
  • Maps — Lake Pulse / GWI Leaflet maps draw tiles (not grey boxes).
  • Report export — download a report (PDF/Excel) and confirm the file opens.
  • Routing on refresh — hard-refresh a deep route (e.g. /monitoring); it loads instead of 404ing (confirms the SPA rewrite).
  • Errors are captured — no unexpected errors flooding the console; Sentry is receiving events.

If any box fails, jump to the matching symptom below.

Local dev sanity check​

After npm start (or npm run start:app <app>):

  • Dev server compiles and opens on http://localhost:4200.
  • You know which backend you're on. Check constants.currentEnv in libs/shared/src/constants/constants.js — it defaults to prod. See Local environment & backend switching.
  • Login succeeds against that backend.
  • Hot reload works on a trivial edit.

"Something's down" runbook​

Work symptom → most-likely cause. Always start with the browser Console and Network tabs open.

Blank / white screen​

  1. Console errors? A red module/render error usually means a bad build or a broken import — check the most recent code change.
  2. Assets 404? If main.[hash].js / styles.[hash].css fail to load, the deploy pointed at the wrong build folder. Re-run the deploy (the scripts set the public path); confirm dist/apps/<app>/ was built first.
  3. Stale bundle? Hard-refresh (Cmd/Ctrl+Shift+R); give the CDN a few minutes.

API calls failing​

  1. 401 / 440 → session/token expired. Expected after inactivity; log in again. If it happens immediately on every call, the token isn't being sent — check auth/login flow.
  2. 402 / 420 → subscription/payment gate, not a bug. Check the account's subscription status.
  3. 500 → backend error. The frontend is fine; check the backend/API service and share the failing request with the backend owner.
  4. CORS / blocked / net::ERR → the request origin isn't allowed. On a fresh deploy this is usually the Content-Security-Policy connect-src in firebase.json not listing the API/WebSocket host. Verify the target's CSP.
  5. Wrong data / wrong environment → you're pointed at the wrong backend. Check constants.currentEnv.

To see exactly what's being sent: flip logRequest / logResponse / logCURL to true in constants.js (see Debug flags). logCURL prints each call as a cURL command you can replay in a terminal to isolate frontend vs backend.

Login / SSO broken​

  1. Redirect loop or "redirect URI mismatch" → the auth redirect URI doesn't match. It's driven by azureAdEnv in constants.js and the redirect config in authConfig.js; the deployed origin must be registered with the identity provider (Azure AD / Google).
  2. SSO button does nothing → check microsoftSignInEnabled / googleSignInEnabled in constants.js.

Real-time not updating​

  • Confirm a live socket in Network → WS. If the wss://...webpubsub.azure.com connection is missing or repeatedly closing, check the WebSocket host is allowed in the CSP and that the backend event hub is up.

Maps not rendering​

  • Grey tiles usually mean the Leaflet tile host is blocked by CSP or unreachable — check img-src / connect-src for the tile provider.

Diagnostic tools & flags​

ToolWhereUse for
Browser ConsoleDevToolsJS errors, render failures
Browser Network (incl. WS)DevToolsAPI status codes, CORS, WebSocket health
logRequest / logResponse / logCURLconstants.jsTrace/replay API calls
Sentry@sentry/react (wired in the app)Captured runtime errors across users
constants.currentEnvconstants.jsConfirm which backend you're hitting

Reference: API error codes​

Defined in constants.js (constants.request.error):

CodeMeaningIs it a bug?
400Bad requestUsually a client/payload issue
401Session expiredNo — re-login
402 / 420Payment / subscription requiredNo — subscription gate
440Token expiredNo — re-login
404Object not foundDepends
500Server errorBackend — escalate

Next Steps​