#Troubleshooting
Common Krate errors and how to fix them.
#Build fails with expected X, got EOF
A construct is unterminated. Common causes:
- An unclosed JSX element (
<div>with no</div>). - An unclosed expression or string.
- A missing
)or}.
The diagnostic points at file:line:col; check the line it names and just
before it.
#spawn .../bin/krate EACCES
The compiler binary is not executable. Krate restores the bit on an installed
binary when it can, so this means it could not: node_modules belongs to another
user, or the volume is mounted noexec. Reinstall as the user who runs krate,
or run chmod +x on the path in the error. 0.5.0-beta.2 shipped without the bit
and has no automatic repair; see Upgrading.
#config uses imports/requires but could not be executed
The compiler could not evaluate krate.config.ts in-process (esbuild plus the
embedded JS runtime). This usually means a dependency is missing. Run
npm install in the project root, then retry.
#@krate/runtime / @krate/components not found
The Node sidecar and bundler resolve packages from node_modules. Install the
dependencies:
npm installIf you use SSR, ensure @krate/runtime is installed (it ships the sidecar
renderer).
#CSS classes have no effect
- Tailwind: classes are collected from the files listed in
tailwind.content(defaults tosrc). A class built dynamically (e.g."text-" + color) cannot be detected - use a full literal class name, or add the file tocontent. - CSS Modules: import the module and reference
styles.foo; a bare class name in a.module.cssimport is scoped.
#Dev server 404s / no hot reload
- The watcher ignores
dist,.krate,node_modules, and_-prefixed files. - If you renamed a page, wait for the rebuild banner; a compile error blocks the reload (the browser shows a build-error overlay).
- Check the terminal for
Watching ... for changes.
#krate check fails on an intentional pattern
Disable the specific rule rather than the whole category:
checks: {
rules: {
"a11y/color-contrast": "off",
"perf/js-budget": "warning",
},
failOn: "error",
}See Quality Checks for the rule list.
#SSR pages return stale ISR content
- ISR serves cached HTML and refreshes in the background. Increase/reduce
revalidateon the page to change cadence. - Missing or slow refreshes: check the terminal for
ISR revalidation failed. - The cache persists to
dist/.krate/isr-cache.json; delete it to force a cold start.
#Port already in use
Set a different port:
devServer: { port: 3210 }The SSR renderer uses devServer.port + 10 (override with ssr.rendererPort).
#Generated JS is larger than expected
- Run
krate check-perf/js-budgetreports per-route JS. - Move logic into a server component (
// @serveror*.server.tsx) so it ships no client JS. - Confirm you are not importing a large module into a client component.
#Type errors on generated routes/content
Run krate types to regenerate .krate/types/*.d.ts, then npx tsc --noEmit.
Editors cache declarations - reload the TS server if types look stale.
#Imports
cannot resolve import- the build stops at the import statement when a relative path, atsconfigpath alias or an npm package cannot be found. Check the spelling and extension (./util.jsfindsutil.ts), thebaseUrlandpathsintsconfig.json, or runpnpm add <package>.- JSON,
?rawand?url-import data from "./data.json"(default, named or namespace imports),import text from "./note.txt?raw"(the file as a string) andimport logo from "./logo.svg?url"(the hashed asset URL) are inlined as constants, so they render in static HTML and are available to client code. Invalid JSON is reported with its file, line and column. - npm packages in client code - functions imported from an npm package
(
import { format } from "date-fns") and called from handlers, effects or expressions are bundled for the browser into the page script, tree-shaken and resolved with thebrowser(anddevelopmentorproduction) export conditions. Node built-ins (node:fs) cannot run in the browser and are reported where they are imported. package.jsonimports(#util) resolve like Node. Workspace packages that ship Krate TSX source are compiled as source.- Source maps - with
--sourcemapthe hydration script maps event handlers and expression bindings back to their position in the.tsxfile.
Last updated: 2026-11-17
Contributors: Noinkin