Troubleshooting
Common symptoms, what causes them, and how to fix them.
On this page
The build stops with static build needs pathnames for …
Cause
No URL that paths returned fits a route with parameters, and a build cannot invent the values itself.
Fix
List that route’s URLs with the paths option of framework().
The build stops with the "paths" option supplied pathnames no route wants
Cause
A URL that paths returned matches no route — most often a typo.
Fix
Fix the URLs the error lists, or drop them from paths.
The build stops with static build cannot ship Server Actions
Cause
A module declares 'use server'. A file cannot receive a form submission, so this mode has no Server Actions.
Fix
To receive the submission on a server, move to @k8ordo/server. A GET form, such as a search or a filter, needs no Server Action.
The build stops with static build cannot run guard.ts
Cause
There is a guard.ts under routes/, and a file has no request to let through or to stop.
Fix
If requests do need stopping, move to @k8ordo/server; otherwise delete the guard.ts.
The build stops with static build could not render …
Cause
A Server Component threw while the page was being rendered — or a client component did, with no Suspense boundary above it.
Fix
The thrown message is logged above that line, beside the page’s URL. Start from there.
A page that shows under vite dev stops the build
Cause
vite dev writes no files and renders per request. It renders a value paths does not list, and answers a Server Component that threw with a 500 and keeps going.
Fix
Run vite build before you ship, and follow the message it stops with.
404.html is served with a 200
Cause
The status that goes with 404.html is the host’s to decide. A build can write the page, but not the response.
Fix
Configure the host to answer an unknown URL with 404.html under a 404.
An error says the "csp" option cannot go into a page's <meta> as it is
Cause
The csp option holds a directive a <meta> ignores — frame-ancestors, report-uri or sandbox — or 'strict-dynamic'.
Fix
Set the directives a <meta> ignores as headers at the host, and drop 'strict-dynamic': the framework’s module script is allowed by 'self'.
Hydration fails, but only in production
Cause
The whole document the root layout renders is hydrated, and some CDNs rewrite HTML on the way. With web-font inlining, email obfuscation or script deferral turned on, the HTML no longer matches the tree React reconciles.
Fix
Turn that feature off. Serving fonts and scripts from your own origin, rather than linking them from another, leaves the CDN nothing to rewrite.
The paths href() takes and a page’s params are not typed
Cause
The include in tsconfig.json does not reach .k8ordo/. The name starts with a dot, so an entry naming only the directory, ".k8ordo", skips it.
Fix
List it with a glob: .k8ordo/**/*.ts.
Right after a clone, params are typed as strings
Cause
.k8ordo/ is generated and not in git, so a fresh clone does not have it yet. Without the route table, params in PageProps is typed as strings rather than as the schemas’ output.
Fix
Run vite dev or vite build once before tsc, so .k8ordo/ gets written.
The build stops with routes/ holds only page.tsx, …
Cause
Something under routes/ is not a route file name — page.ts, with the wrong extension, included.
Fix
Move components and data under a directory whose name starts with _, such as _parts/. For a page, use the .tsx extension.
An error says a params schema must validate synchronously
Cause
The paramsSchema validates asynchronously. Which route answers a URL is decided before anything renders, and that decision cannot wait.
Fix
Keep the schema to the shape of the value. Check whether the data exists in the page, and throw notFound() when it does not.
The build stops with 'server-only' cannot be imported in client build
Cause
A module that imports server-only is reached from a client component. The lines below the first are the chain of imports that got it there.
Fix
Do not import it from the client component. Read it in a Server Component and pass the values down as props.
An error says Functions cannot be passed directly to Client Components
Cause
A Server Component passes a function to a client component as a prop. Props are serialized on the way, and a function cannot be.
Fix
Pass the value the function returns, or move the function into the client component.
An error says useRoute must render inside a matched <Router>
Cause
Under the framework the browser holds no route table, since the tree comes from the server. useRoute() and useParams() have no route to read.
Fix
Pass the params the page received down to the client component as props. Read the current URL with usePathname().