05 — admin_console_R: where to look
A symptom → location routing table.
Dev server / build issues
| Symptom |
First place to look |
npm run dev fails on a TS error |
tsconfig.app.json; the build won't tolerate type errors |
| Vite "Failed to resolve import" |
Path alias @ configured in both tsconfig.app.json and vite.config.ts — make sure your import uses @/... correctly |
| HMR doesn't reflect changes |
Restart npm run dev; some changes (config files) require a full restart |
| HMR overlay never appears |
vite.config.ts → server.hmr.overlay: false — error overlay disabled; check terminal |
| Tailwind class doesn't apply |
tailwind.config.ts → content must include your file path; rebuild |
Auth issues
| Symptom |
First place to look |
| Login fails |
Network tab — is VITE_API_URL correct? Does the BE return the expected shape? |
Stays on /login after successful login |
AuthContext.tsx → login(); is it updating state? Is ProtectedRoute re-rendering? |
| Logout doesn't fully log out |
Check AuthContext.tsx → logout() — does it clear localStorage AND state? |
| User stays logged in after token expires |
checkAuth() rehydrates from localStorage; the FE doesn't know about expiry until the BE 401s |
Apptype header wrong |
src/services/api.ts hardcodes "admin-console" — known finding F-2 |
| Reference |
../../audit/admin_console_R/authentication-client.md |
Routing issues
| Symptom |
First place to look |
| 404 on a page |
App.tsx → <Routes> — is the path registered? |
| Page renders without the sidebar |
The route isn't wrapped in <AppLayout> |
| Protected page accessible when logged out |
The route isn't wrapped in <ProtectedRoute> |
| Reference |
../../audit/admin_console_R/routing-and-state.md |
Data fetching issues
| Symptom |
First place to look |
| Query returns stale data |
TanStack Query cache — invalidate via queryClient.invalidateQueries({ queryKey: [...] }) in your mutation's onSuccess |
| Multiple identical refetches |
Query keys are different in subtle ways (object reference vs primitive) — log the key |
| Query refetches on every tab focus |
TanStack Query default — pass refetchOnWindowFocus: false to the query options if undesired |
| Mutation succeeds but UI doesn't update |
The mutation isn't invalidating the relevant query |
| API call returns 401 unexpectedly |
Token expired OR role/permissions check failed BE-side |
Role-gating issues
| Symptom |
First place to look |
| Wrong users see a nav item |
Sidebar.tsx — check the role gate; verify ENV.<ROLE> value vs what the BE returns |
| FE hides a nav item but the route is still accessible |
Add a role check in the page itself (or in ProtectedRoute extension) — ProtectedRoute only checks logged-in-ness |
ENV.SUPER_ADMIN is NaN |
The env var is missing or unparseable; the env code does Number(...) |
| Symptom |
First place to look |
| Validation error not showing |
The shadcn form primitives expect react-hook-form's context — verify <FormProvider> wraps the inputs |
| Zod schema not enforced |
Confirm resolver: zodResolver(schema) is passed to useForm |
| Submit doesn't fire |
Form's onSubmit may be on the wrong element; use form.handleSubmit(handler) |
UI / styling issues
| Symptom |
First place to look |
| Tailwind class doesn't apply |
tailwind.config.ts content paths; cn(...) may be merging incorrectly |
| Dark mode wrong |
darkMode: 'class' — toggle a dark class on the <html> element |
| shadcn primitive looks wrong |
The primitive lives in src/components/ui/<primitive>.tsx; edit it directly |
| Sonner toast doesn't appear |
<Sonner /> must be mounted in App.tsx |
| Icon missing |
lucide-react — import the specific icon |
Build / deploy issues
| Symptom |
First place to look |
| Build succeeds locally but fails in CI |
No in-repo CI; ask the team which environment runs the build |
| Production page is blank |
Browser console — likely a runtime TS-stripping issue or an env var missing in the build env |
| Lovable.dev script breaks SSR / preview |
The script is loaded unconditionally; consider gating to import.meta.env.PROD ? null : ... in index.html |
| Reference |
../../audit/admin_console_R/build-and-deploy.md |
Security findings to be aware of
| Finding |
Where |
Apptype header hardcoded |
src/services/api.ts (F-2) |
| Lovable.dev runtime in production HTML, no SRI |
index.html |
Token in localStorage |
src/context/AuthContext.tsx |
| Role IDs as env vars (drift risk) |
src/config/env.ts |
| Reference |
../../audit/admin_console_R/security.md |
When all else fails