Module Troubleshooting

Start from the owning module, identify the failed boundary, and verify the smallest observable state before changing code.

On this page

Failure matrix

Module	Symptom	Inspect first	Verify
Account	Profile or security updates fail.	Session profile, action validation, and persistence result.	Run account feature tests and retry as the signed-in user.
Analytics	Charts are empty or inconsistent.	Requested range, source table rows, enabled billing models, and server aggregation.	Call the range API and compare its response with stored events.
Billing	Setup, checkout, portal, or local history fails.	Billing setup readiness, active provider, catalog, webhook event state, and customer mapping.	Use provider test mode and confirm local projection rows.
Branding	Logo, favicon, or appearance does not update.	Admin guard, upload validation, branding row, and public settings cache.	Reload public and dashboard surfaces after a successful write.
Compliance	Security or audit pages are empty.	Super-admin guard, audit rows, role redaction, and retention history.	Run compliance tests and query a known audit action.
Contact	Messages are rejected or missing.	Schema validation, Turnstile, rate-limit decision, insert result, and queued notification.	Submit once with a fresh request and inspect contact_messages.
Customers	A customer is absent or incomplete.	Provider customer id, pagination filters, local billing projection, and explicit sync support.	Search by provider id and inspect related billing rows.
Docs	A guide is missing or stale.	Content registration, navigation registration, source references, and route resolution.	Run feature tests and open the affected route.
Notifications	Email remains queued, failed, or dead-lettered.	Outbox status, attempt count, error category, template, recipient resolution, and Resend status.	Run one bounded worker batch and inspect the resulting row.
Posts	Content cannot publish or render.	Editor validation, scheduled timestamp, persistence result, route revalidation, and public query.	Preview the record and run the posts feature tests.
Settings	A saved value reverts or is ignored.	Action guard, schema normalization, persisted settings_json, and env lock behavior.	Reload through the server query and compare normalized output.
Team	Invite or role changes are denied.	Current role, feature permission, invite schema, service result, and audit entry.	Run team access tests with super_admin and user roles.
Waitlist	Signup, confirmation, export, or mode behavior fails.	Current mode, payload validation, Turnstile, rate limit, token state, and admin guard.	Exercise the exact API path and inspect waitlist_signups.

Troubleshooting boundaries

Authentication and access

Session profile and route guards explain most account and admin authorization failures.

src/lib/auth/session/profile.ts
src/lib/auth/guards/route.ts
src/lib/auth/rbac/server.ts

Provider readiness and retries

Billing setup and notification worker state expose provider configuration and retry failures.

src/features/billing/server/runtime/readiness.ts
src/features/notifications/server/outbox/services/worker.ts

Public request protection

Shared rate limits and feature schemas explain rejected contact and waitlist requests.

src/lib/security/rate-limit/check.ts
src/features/contact/shared/schemas.ts
src/features/waitlist/server/signup/schemas/payload.ts

Data and operational cleanup

Migration constraints and retention behavior explain missing, rejected, or cleaned operational rows.

supabase/migrations/20260426000000_init.sql
src/features/compliance/server/retention/service.ts

Troubleshooting rule

Reproduce the smallest failing request or action before editing code.
Record the request id, profile id, provider event id, or job id when available.
Inspect local persisted state before calling an external provider again.
Treat retries, duplicates, and partial state as expected failure modes.
Add a regression test when the failure exposed a missing prevention path.