Troubleshooting

Common issues and where to look first.

App

Symptom	Likely cause / fix
Blank page / lazy route won't load	A bad import in a lazy-loaded page. Check the browser console; verify the import path in AppRoutesConfig.jsx.
Component test fails on mount	A bad react-icons/ri import — the L3 mount test is designed to catch exactly this. Fix the icon name.
Theme looks wrong in light mode	A conditional class not guarded by isLight, or a hardcoded color. Audit with cn() + isLight.
supabase.from is not a function in a test	Architecture violation — something called from(). Move the read to an RPC hook.
Stale data after a write	The read hook's cache TTL hasn't expired; call refetch() after the mutation, or lower the TTL.

Edge functions

Symptom	Likely cause / fix
401 from an EF	JWT missing/expired; requireAuth rejected it. Re-auth on the client.
403 from an EF	Ownership/role check failed — the row isn't the caller's.
Generic 500	An unhandled error was caught by err(); check the structured logs (search the event field).
Webhook processed twice	Idempotency missing — ensure the UNIQUE event-id upsert is in place.
Webhook 401	Signature/timestamp invalid — check the secret and the replay window.

Database / migrations

Symptom	Likely cause / fix
RLS blocks a legitimate read	Policy too strict, or the read should go through a SECURITY DEFINER RPC.
Migration won't apply	Don't edit an existing migration — add a new one. Check naming YYYYMMDD_NNN_….
RPC returns no new column	If not using row_to_json(table.*), update the RPC's projection.

Docs portal

Symptom	Likely cause / fix
docs:dev fails to start	Run npm --prefix documentations/portal install first.
Reference page out of date	Re-run npm run docs:gen.
Dead-link warnings on build	Fix the link or rely on ignoreDeadLinks in .vitepress/config.mjs (set for WIP stubs).