Troubleshooting

Common Vite and TanStack Router errors in this project and how to read the enhanced stack traces.

How to read the enhanced traces

  • Dev error panel — every route error renders the message, file:line:column, the Vite plugin that produced it, a code frame, and the full stack with cause chain.
  • [import-chain] logs — printed in the dev terminal when an import fails to resolve. Shows the failing specifier and the chain of files that imported it.
  • Source-mapped server traces — Cloudflare uploads sourcemaps, so stack frames in worker logs point at the original .ts file/line, not the bundled output.
  • Sourcemap guard — the build fails if any chunk is emitted without a .map sibling or sourceMappingURL reference, so traces are never silently lost.

Common issues

Failed to resolve import "…"

Symptom
Browser overlay or terminal shows `[plugin:vite:import-analysis] Failed to resolve import`.
Cause
The imported path doesn't exist, the package isn't installed, or the file extension/casing is wrong.
Fix
Check the `[import-chain]` log in the dev terminal — it prints the failing specifier and the chain of importers so you can find which file pulled in the bad path. Create the missing file, fix the path/alias, or install the package.

Cannot find module '@/…'

Symptom
TS or runtime error referencing an `@/` alias path.
Cause
The aliased file doesn't exist yet, or you moved/renamed it without updating imports.
Fix
Create the file before importing it, or update the import to the new path. Aliases resolve from `src/`.

React is not defined

Symptom
SSR/runtime crash referencing `React.forwardRef`, `React.memo`, or similar.
Cause
The automatic JSX transform doesn't bind the `React` namespace at runtime — only JSX syntax works without an import.
Fix
Add `import * as React from "react"` (or import the specific API like `forwardRef`) at the top of the file.

Transform failed with X parser error

Symptom
Vite reports `Transform failed` with a file:line:column from esbuild or SWC.
Cause
Syntax error — unmatched JSX tag, missing closing brace, stray characters from a partial edit.
Fix
Open the file at the reported `file:line:column`. The dev error panel renders the code frame so you can see exactly which token is wrong.

Route matched but page is blank

Symptom
URL is correct, no error, but nothing renders.
Cause
A parent route file (e.g. `__root.tsx` or a layout) is missing `<Outlet />`.
Fix
Ensure every parent route with children renders `<Outlet />` in its component.

{"unhandled":true,"message":"HTTPError"}

Symptom
Production responses return a generic 500 with that JSON body.
Cause
h3 swallowed an SSR error. The wrapper in `src/server.ts` rewrites this to a branded error page and logs the captured error.
Fix
Open server logs — the underlying `Error` is printed with a mapped TS stack (thanks to `upload_source_maps`).