Every stable KRxxxx diagnostic code the Krate compiler reports, with an explanation.
#Diagnostic Codes
Krate diagnostics that point at a known compatibility limit carry a stable
code such as KR2001. The code appears in the message
(file.tsx:3:5: [KR2001] ...), never changes meaning once released,
and is listed here with the reason it is reported and what to do instead.
Codes are grouped by area:
| Range | Area |
|---|---|
KR1xxx |
syntax and parsing |
KR2xxx |
React effects, dependency arrays and hooks |
KR3xxx |
class components and error boundaries |
KR4xxx |
Suspense, lazy, use() and transitions |
KR5xxx |
events, forms and refs |
KR6xxx |
lists and keys |
KR7xxx |
React 19 actions and server actions |
KR8xxx |
islands, compiled packages and general React compatibility |
KR9xxx |
routing, segment pages and rendering errors |
#KR1xxx: syntax and parsing
No codes are registered in this range yet.
#KR2xxx: React effects, dependency arrays and hooks
#KR2001
Dependency array is not statically resolvable
The dependency list is a binding the compiler cannot resolve to an array literal in the same component (for example a parameter or an imported value). It is compared element by element (Object.is) whenever it is re-read, but Krate components run once, so a captured array never changes and the hook runs only on mount. Write the array inline, e.g. useEffect(fn, [a, b]), or bind it with const deps = [a, b] in the component body.
#KR2002
Effect without a dependency array
React runs such an effect after every render. Krate has no re-renders, so the effect re-runs after every commit that changes the component's own state (useState/useReducer) or its props, which is when React would have re-rendered it because of its own state or props. Re-renders caused only by a parent or a context are not modelled. Pass an explicit dependency array to make the trigger explicit, or [] to run once.
#KR2003
Async effect callback
An async function returns a Promise, not a cleanup function, so its cleanup is ignored (React warns about this too). Declare an async function inside the effect and call it, returning a synchronous cleanup.
#KR2004
useCallback without a dependency array
React returns a new function on every render when the dependency array is omitted. Krate components run once, so the callback keeps one identity for the component's lifetime; effects or memos that list it as a dependency do not re-run. Pass the dependency array the callback reads.
#KR2005
useMemo without a dependency array
React recomputes such a memo on every render. Krate recomputes it when a signal it reads changes, which matches whenever the value depends only on state and props. Pass the dependency array to make recomputation explicit.
#KR2006
Dependency argument is not an array
The second argument of useEffect/useLayoutEffect/useInsertionEffect/useMemo/useCallback must be an array (React warns otherwise). The value is ignored and the hook is treated as having no dependency array. Pass [a, b] or omit the argument.
#KR2008
Hook called inside a condition or loop
React requires hooks to be called in the same order on every render (the Rules of Hooks), so a hook inside an if, switch or loop is undefined behaviour in React (it throws when the hook count changes). Krate runs the component once and would bind whatever the first run created. Call the hook unconditionally at the top level and branch on its result, or move the repeated or conditional part into a child component that calls the hook.
#KR3xxx: class components and error boundaries
#KR3001
Class component has no render method
A React class component must define render(). Without it Krate cannot lower the class and the component renders nothing. Add render() returning JSX, or convert the class to a function component.
#KR3002
Unknown instance property on a class component
The class reads this.
#KR3003
Unsupported static class member
Only defaultProps, propTypes, displayName, contextType, getDerivedStateFromProps and getDerivedStateFromError are lowered. Other static fields, methods and static blocks have no instance equivalent after lowering; move them to module scope next to the component.
#KR3004
Computed class member name
Class members named with a computed key ([expr]) cannot be resolved at build time. Give the member a plain name.
#KR3005
componentWillMount is not supported
UNSAFE_componentWillMount (and componentWillMount) runs before the first render, which Krate performs at build time. Initialize state in the constructor or a state field, and move side effects to componentDidMount. componentWillReceiveProps and componentWillUpdate (and their UNSAFE_ forms) are supported.
#KR3006
Legacy class context is not supported
static contextTypes and childContextTypes (the pre-16.3 context API) are not lowered. Use static contextType = MyContext and this.context, or a function component with useContext.
#KR3007
this inside a static lifecycle
getDerivedStateFromProps and getDerivedStateFromError are static: React calls them without an instance and Krate lowers them to plain functions. Use their parameters instead of this.
#KR3008
Error boundary without getDerivedStateFromError
A class with componentDidCatch but no static getDerivedStateFromError catches errors, but React has no state update to render a fallback with: the failed subtree is unmounted and its last DOM stays on the page until componentDidCatch calls setState. Add getDerivedStateFromError returning the fallback state.
#KR3009
Error boundary rendered its fallback at build time
A component inside an error boundary threw while the page was built. Krate rendered the boundary's fallback (the state returned by getDerivedStateFromError) instead of failing the build, and calls componentDidCatch when the page hydrates. Fix the error, or keep the fallback if it is expected.
#KR3010
Component threw while the page was built
A component threw (a throw statement ran) while Krate rendered the page at build time, and no error boundary encloses it, so the build fails. Fix the error, guard it with a condition, or wrap the component in an error boundary to render a fallback instead.
#KR3011
Class component is not lowered
Krate lowers class components declared at module top level (class X extends Component, exported or not). A class expression or a class declared inside a function is not lowered and renders nothing. Move the declaration to module scope or convert it to a function component.
#KR4xxx: Suspense, lazy, use() and transitions
#KR4001
lazy() loader is not a static import()
Krate code-splits lazy components at build time, so the loader must be () => import("./Component") with a string literal path (optionally .then((m) => m.Named) or .then((m) => ({ default: m.Named })) for a named export). Computed paths and other loaders cannot be resolved.
#KR4002
lazy() is not declared at module level
Declare lazy components once at the top level of a module (const Chart = lazy(() => import("./Chart"))). React re-creates a lazy component declared inside a component on every render, and Krate cannot split it.
#KR4003
use(promise) is not assigned to a variable
Krate lowers use(promise) to a reactive value, so it must initialize a declaration in the component body: const user = use(userPromise). The call may be conditional inside that initializer. use(Context) works anywhere.
#KR4004
use(promise) result is destructured
The value of use(promise) is reactive and is read through its variable. Assign it first and read fields from it: const user = use(p); user.name.
#KR4005
Krate components do not re-render, so there are no commit timings to report.
#KR4006
lazy() of a package is not code-split
Only local modules are split into separately loaded hydration chunks. A lazy package import is compiled like a static import of that package.
#KR4007
lazy() module has no default component export
The module passed to lazy() must export default a function component, or the loader must map a named export: import("./X").then((m) => ({ default: m.Named })).
#KR4008
Component suspends outside a
A component reads use(promise) or a resource but no
#KR5xxx: events, forms and refs
#KR5001
Unknown event handler prop
React ignores on* props on built-in elements that are not React DOM events (and warns). Krate still attaches a native listener for the lowercased event name. Fix the spelling, or listen for a custom DOM event with ref.current.addEventListener in an effect.
#KR5002
Lowercase event handler prop
React event props are camelCase (onClick, onChange). A lowercase prop such as onclick is not an event handler in React and the function is never called. Use the camelCase name. krate fix rewrites unambiguous lowercase handlers; string-valued inline handlers are left alone.
#KR5003
String ref
String refs (ref="name") were removed in React 19 and are ignored. Use useRef or createRef and pass the object (ref={inputRef}), or pass a callback ref.
#KR5004
Controlled form field without onChange
A form field with value (or checked) is controlled: after every edit the DOM is restored to the prop, so without an onChange handler it is read-only (React warns). Add onChange, use defaultValue/defaultChecked for an uncontrolled field, or mark it readOnly.
#KR5005
Both value and defaultValue
A form field must be either controlled (value/checked) or uncontrolled (defaultValue/defaultChecked), not both. The default is ignored; remove one of the props.
#KR5006
Form field switches between controlled and uncontrolled
value={cond ? x : undefined} makes the field uncontrolled while the expression is undefined and controlled otherwise; React warns when it switches. Use an empty string (or false for checked) instead of undefined so the field stays controlled.
#KR5007
onChange on a contentEditable element
React's onChange only fires for input, textarea and select. A contentEditable element never receives it; listen with onInput instead.
#KR5008
ref.current read during render
React shows the ref's value as of the latest render, so a later state update reveals a mutated ref.current. Krate components render once and bind only state, so a ref read in JSX is shown once and never refreshed. Keep values the UI shows in state, or read the ref in an effect or event handler.
#KR6xxx: lists and keys
#KR6001
Each child in a list should have a unique key prop
A list whose items can change at runtime (its array reads a signal, state or a runtime value) returns elements without a key, so rows are matched by index. When items are reordered, inserted or removed, row state (input values, focus, component state, effects) stays with the position instead of following the item, exactly as in React. Add a stable, unique key from the item, for example
#KR6002
Encountered two children with the same key
Two items of a list resolve to the same key at build time. Keys must be unique among siblings so each row keeps its identity. The runtime also logs a console error when it sees duplicates; it keeps the first occurrence on its existing row and renders each duplicate as a separate row. Use an id that is unique per item.
#KR6003
List callback keys only some of its elements
A map callback returns a keyed element on some paths and an unkeyed one on others (for example a ternary with a key on one branch). Unkeyed rows fall back to their index, which mixes identities. Put the same key on every returned element.
#KR7xxx: React 19 actions and server actions
#KR7001
Inline "use server" function
A "use server" directive at the top of a function inside a component is hoisted into a server action. It is rejected inside a "use client" module, in a class, when it uses this, and when it captures values in a page that is prerendered (captured values are sent to the browser encrypted and need a per-request render, as in an async or dynamic page). Move the function into a module whose first statement is "use server" and import it, or declare it inside an async server component.
#KR7002
useFormStatus() component does not render an element
Krate finds the form a useFormStatus() call belongs to from the DOM element the component returns. When the component returns another component, a string, or nothing, the status cannot be connected and always reads as idle. Return a DOM element (for example the submit
#KR7003
useActionState initial state is not known at build time
A form whose action is a useActionState dispatch around a server action still posts to the action URL without JavaScript. The previous state for that submission is the initial state, encoded into the URL at build time; when it cannot be evaluated the server receives null.
#KR7004
"use server" module exports a non-function
Every export of a "use server" module becomes a public endpoint and must be a function. An export built by a wrapper call (export const save = createAction(...)) is accepted and checked when the module loads; a literal, object, array or class can never be an action and is rejected at build time.
#KR7005
"use server" module uses a star re-export
A star re-export (export * or export * as) cannot be turned into named endpoints. Re-export the actions by name: export { save } from "./other".
#KR7006
Imported server action does not exist
The import names an export that the "use server" module does not declare.
#KR7101
Async layout cannot be used here
An async layout renders per request in the SSR sidecar, with the page and the layouts inside it, instead of being baked into the static shell. It can await data and gate its subtree with redirect() or notFound(). An error.tsx below it is the error boundary of the page and renders on the server when the page throws. It cannot sit above a template.tsx in the same route (a template hydrates in the browser), and a layout that is baked at build time for another reason (an intercepting or segment route) cannot be async. Move the template above the async layout, or make the layout synchronous and fetch data in an async child component.
#KR7102
await cannot run at build time
Only async components (server components) can await: they render per request in the SSR sidecar. Code that Krate evaluates at build time, such as module-level constants a static component renders or a non-async component body, cannot await a Promise. Mark the component async or compute the value without awaiting.
#KR7103
Server components need request-time rendering
An async component renders per request, but output: "static" disables the SSR sidecar, so the page cannot render it. Remove output: "static" or make the component synchronous.
#KR7104
Page with server components is rendered per request
A page that contains an async component cannot be fully baked at build time. Krate bakes the rest of the page as a static shell and renders each server component per request (streaming mode). This is informational.
#KR7105
Server component props must be known at build time in a static page
A server component used from a synchronous page renders as its own request-time region, so its props are fixed when the page shell is built: they must be literals, module constants or route params, and it cannot receive children. Make the page itself async (the whole page then renders per request) or pass constant props.
#KR7110
Client-only API used in a server component
Server, static and runtime components, and the components an async component renders, render once (at build time or per request) and ship no JavaScript, so hooks such as useState/useEffect, Krate signals, class state and lifecycles, and event handlers cannot work there; they used to build and leave a page that did nothing. Remove the server tier from the component (the // @server comment or decorator, the .server file name or the config entry) to make it a client component, or move the interactive part into a client child component (one with no tier, or marked @client, or a module that starts with "use client" under an async component) and render that from the server component; it is server-rendered and then hydrated in the browser.
#KR7111
Function prop passed from a server component to a client component
Props crossing from a server component to a "use client" component are serialized to JSON. Functions (other than server actions), class instances and symbols cannot be sent. Define the handler inside the client component, or pass a server action. The same check runs at request time for values computed while rendering.
#KR7112
Client component imports a server-only module
A module that imports server-only must never reach the browser, but a "use client" module (directly or through its imports) imports it, so it would be bundled into the client chunk. Import it from a server component instead and pass the data as props.
#KR7113
Async component in a client module
Components in a "use client" module run in the browser and cannot be async. Move the async component to a module without the directive (it becomes a server component).
#KR7114
Client module exports cannot be listed
Krate wraps each export of a "use client" module in a client boundary, so it must know the export names. export * from a local module is expanded into that module's runtime exports; one that cannot be enumerated (a package, or a cycle of export *) must list the re-exported names explicitly (export { A, B } from "./x").
#KR7115
Tier decorator cannot apply here, or two tiers conflict
@server, @static, @runtime and @client go on a function, class or const declaration, once per declaration. An async component always renders per request, so only @runtime fits it. A runtime component is bundled per file, so @runtime must be on the default export or the only exported component of its file. A component also has one tier: the leading // @tier comment, the .server/.runtime/.static file name, the serverComponents, runtimeComponents, serverDirs and runtimeDirs config entries, a decorator and a "@tier" string at the top of a function body must agree. A decorator on a component that is not the file's default export or only exported component may override the file's tier (@client in a // @server file); on the default export it must match. See "Tiers that disagree" in Component Tiers.
#KR7116
One name imported from two modules
Two modules export the same name and a page imports it from both, for example import { Card as A } from "./a" and import { Card as B } from "./b". Modules on a page share one namespace, so Krate gives one of the exports a private name and rewrites the imports to match, and this is not reported. A named re-export (export { Card } from) is rewritten to follow the rename too. It is reported when neither module can be renamed because something reads export names from source: export * or export * as, an import followed by an export, the page's own module, an import(), a "use client" or "use server" module, or an alias export (export { x as Card }). Both imports then resolve to one declaration and the page shows the wrong output. Rename one of the exports. Private names and default exports do not have this problem. This is a warning.
#KR7117
Renderer component must be a client component
A component marked @renderer (or with a "use renderer" or "@renderer" string at the top of its body) hands its children to a non-DOM renderer in the browser, so it always hydrates on the client. It cannot be async, and it cannot also be a static, server or runtime component, whichever way that tier is written (a decorator, a body directive, a leading // @tier comment, a .server/.runtime/.static file name or a config list). Remove the other tier, use @client, or move the renderer component into its own client module.
#KR7120
API route file in the pages directory
API routes are served from src/api, not from the pages directory. A .ts or .js file under src/pages/api used to build into an empty page while /api/... answered 502. Move the file to src/api/. This is a warning.
#KR7121
Prerendered endpoint failed
A file such as src/pages/data.json.ts is a prerendered endpoint: its GET export runs once at build time and the response body is written to the output as a file (data.json). The build fails when the module has no GET export, GET throws, answers a non-2xx status, or the name has a dynamic segment. Endpoints run on Node (or the configured runtime) with the project's environment. For a response that depends on the request, use an API route in src/api.
#KR7122
Page metadata could not be evaluated at build time
A static page's export const metadata and generateMetadata (and those of the layouts above it) run at build time, once per generateStaticParams entry, and become the document <title>, description, canonical link, Open Graph and Twitter tags. This one could not run: it threw, it needs something the build does not have (a browser global, a service that is down), or the module could not be loaded. The segment's tags were left out and the page still builds. Fix the error, or render the page per request (export const dynamic = "force-dynamic", or revalidate = N) so generateMetadata runs with the request. This is a warning.
#KR7123
Sass, Less and Stylus files are not compiled
Krate compiles CSS (including CSS modules and Tailwind) but has no Sass, Less or Stylus compiler, so importing a .scss, .sass, .less or .styl file would ship no styles at all. Compile the file to CSS first (for example with the sass CLI in a prebuild script) and import the .css result, or port the styles to CSS or Tailwind. This is an error.
#KR7124
Name is not exported by @krate/runtime
A named import from @krate/runtime (or one of its subpaths) asks for something the package does not export. The import is removed from the page, so the name would be undefined in the browser and fail with a ReferenceError. Check the spelling against the runtime API reference; names from other frameworks (signal, usePathname) have Krate equivalents such as createSignal and getNavigationState. This is an error.
#KR7125
tsconfig baseUrl and paths disagree
compilerOptions.paths targets resolve against baseUrl, in tsc and in Krate. A baseUrl of ./src together with "@/*": ["./src/*"] points at src/src, which tsc cannot find. Krate 0.4 ignored baseUrl for aliases, so a project scaffolded then still has this shape. Krate reads such a target relative to the project root when it exists there and not under baseUrl, so the build works, and reports this warning once. krate fix --apply sets baseUrl to "." when every target repeats the baseUrl directory, which also makes tsc and your editor agree. A target that exists in neither place is still an error ("cannot resolve import ... matched tsconfig path alias"). This is a warning.
#KR7126
Imported asset is used where its URL cannot be inlined
import logo from "./logo.png" binds the file's hashed URL. The compiler replaces reads of the binding with that URL, in the module that imports the file and in every module that imports it through export { logo }, export default logo, export { default as logo } from "./logo.png", export * or export * as ns and ns.logo. A read it cannot reach, such as a computed property key ({ [logo]: 1 }) or ns.default of a namespace that is passed on whole, has no value in the browser script: it is a ReferenceError there, or renders as the bare name. Use the binding as a plain value in JSX or a component, or import the file with a ?url suffix. This is a warning.
#KR7127
package.json krate.vendor is malformed
A package can list browser code that Krate bundles with esbuild like an npm dependency, instead of compiling it as Krate source: "krate": { "vendor": ["src/engine/"] }. Each entry is a path prefix relative to the package directory; an entry ending in / matches every file under that directory. The list must be an array of strings that stay inside the package (no absolute paths or ..). Fix the package.json of the package named in the message. This is an error.
#KR7130
Metadata route could not be built
A sitemap.ts, robots.ts, manifest.ts, opengraph-image or twitter-image file under the pages directory runs once at build time and its result becomes sitemap.xml, robots.txt, manifest.webmanifest or a PNG. The file threw, returned a value of the wrong shape (a sitemap entry without a url, a robots file without rules), or could not be loaded. Fix the error named in the message. This is an error: the file would otherwise silently produce nothing.
#KR7131
ImageResponse uses something the renderer cannot draw
ImageResponse draws a documented JSX subset with a built-in renderer (no headless browser): flexbox layout, text, colours, gradients, borders, box shadows, opacity, overflow hidden and images. Anything else (an element such as <svg>, a style such as transform or filter, a unit such as vh, a character the font has no glyph for) is listed here instead of being drawn wrong. Use the supported subset, or pass a font with options.fonts for other characters. This is an error.
#KR7132
Image route in a dynamic segment has no params to build with
An opengraph-image or twitter-image file inside a dynamic segment (blog/[slug]/) is built once per entry of the segment page's generateStaticParams. This one has no matching page or no generateStaticParams, so no image was built and no og:image tag is emitted for it. Export generateStaticParams from the segment's page. This is a warning.
#KR7133
A metadata file replaces a plugin or config output
sitemap.ts or robots.ts defines the file, so the sitemap or robots plugin (and the robots and seo config that feed it) did not write its own. The metadata file wins. Remove one of them to silence this warning. This is a warning.
#KR7134
dynamic or revalidate on a metadata route that cannot run per request
A sitemap.ts, robots.ts or manifest.ts that exports dynamic = "force-dynamic" or a revalidate runs per request on the server. This one sits in a dynamic segment (blog/[slug]/), where a per-request route has no URL to answer, so it still runs once at build time and the export is ignored. Move the file to a static directory or remove the export. This is a warning.
#KR7140
Tailwind input found but Tailwind is not enabled
Krate generates Tailwind utility CSS only when tailwind: { enabled: true } is set in krate.config.ts. Without it, @tailwind base|components|utilities and @import "tailwindcss" are removed from your CSS and no utilities are generated, so the page ships almost no styles. The warning appears once per build when a tailwind.config.{ts,js,mjs} file exists or one of those directives is found. Enable Tailwind, or delete the config file and directives if you do not use it. This is a warning.
#KR7141
CSS has unbalanced braces or an unclosed comment
A stylesheet with a { that is never closed, a } with no {, or a comment that never ends is not valid CSS, and browsers recover by dropping or merging the rules that follow it. Krate reports the line and column, and closes the damage at the end of the file so it cannot swallow the next stylesheet in the page: a stray } is removed and a missing one is added. The file is still shipped as written otherwise, so fix the source. This is a warning.
#KR7142
generateStaticParams entry cannot produce a page
Each object returned by generateStaticParams becomes one page, so it needs a value for every dynamic segment of the route ({ slug: "a" } for [slug].tsx), and each value becomes a directory name: it must be non-empty and contain no .., backslash or, outside a catch-all route, /. An entry that misses a param would have been written to the literal path [slug]/index.html; two different entries that produce the same path would overwrite each other. Both are build errors that name the entry. An exact duplicate entry is dropped. Fix the function, or remove the entry.
#KR7143
Middleware file has no handler
middleware.ts must export the function that runs for each request, as export function middleware(request) or as the default export. Without one, requests could not be checked, so this is a build error, and a server running such a module answers 503 instead of letting requests through. Export the handler, or delete the file.
#KR7144
Root-relative URL on a plain tag ignores the base path
The site is served under a base path, but a plain <a href="/x"> or <img src="/x"> is emitted exactly as written, so the browser requests it from the domain root and misses the site. Use <Link href="/x"> for pages, and <Image> or an import for images: both add the base path. Write the full path only when the URL really does belong outside the site.
#KR7145
CSS @import points at a file that does not exist
A relative or package @import in a stylesheet could not be resolved, for example @import './missing.css' after the file was moved or deleted. Krate cannot inline it, and emitting it as written would make the browser request a URL that 404s, so the build fails with the file, line and column. Fix the path or restore the file. Remote @import url(https://...) statements are passed through unchanged, and imports outside the project root keep their separate warning (see cssImportRoots). This is an error.
#KR7146
Build output references a chunk that was not written
After writing the output, Krate checks that every quoted /chunks/... URL in the page HTML, page and island scripts, server bundles and manifests names a file in the chunks directory. A missing chunk means the browser gets a 404 for it, so the island or page script that imports it never runs. This points at a bug in Krate, not in the app: the build fails instead of shipping the broken page. Files copied from the public directory are not checked. Report the error with the URLs it lists. This is an error.
#KR7150
Unknown code theme
markdown.codeTheme names a syntax theme that Krate does not ship, so code is highlighted with the default theme for that colour mode instead (github for light, krate-dark for dark). Use a chroma style name such as github, github-dark, monokai, dracula or nord. Give one name to use it in both modes, or { light: "github", dark: "github-dark" } to pick a theme per mode. This is a warning.
#KR7151
Language cannot be highlighted after the build
Code that is highlighted in the browser (a <Code> whose text changes at run time) or at request time is coloured by a small tokenizer that runs chroma's lexers exactly, and it ships only for a fixed list of languages. The language used here is not on it, so the code is shown as plain text. Build-time highlighting is unaffected and supports every chroma language. Use one of the listed languages (markdown.codeHighlight docs), or make the code known at build time. This is a warning.
#KR7160
API not supported by the embedded API runtime
API routes and middleware run in Krate's embedded QuickJS runtime unless ssr.apiRuntime (or ssr.middlewareRuntime) selects "node", "bun" or "deno". The build scans the modules each route or middleware bundles and reports globals that runtime lacks, such as TransformStream, WebSocket, Buffer or crypto.subtle.encrypt, with the location of the first use in each file. Calling one throws a NotSupportedError carrying the same code at run time. Only global references count: an import or local variable of the same name, a typeof X check and code guarded by one are not reported. In a dependency the warning is reported once per package and API, since libraries often detect features before using them. Follow the hint (most APIs have a portable alternative), or select the Node runtime. A route that imports a node: builtin is served by Node automatically and is not scanned. The full list is in the API runtime compatibility reference. This is a warning.
#KR7170
Host code markers disagree
A native app decides what is host code (it runs in the native process, not the webview) from several sources: a @host decorator or a "@host" string at the top of a function body, a // @host comment on the first line of a file, a .host.ts / .host.tsx file name, the hostFunctions and hostDirs config entries, and .go files, which are always host code. Sources that name host code and something else for the same module conflict: a .go file cannot also carry a tier, and a host module cannot carry // @server, // @runtime, // @static or // @client, a tier file name, or a serverComponents, runtimeComponents, serverDirs or runtimeDirs entry. A function-level marker overrides the file for that function only, so @client on one function in a host file is allowed, but a decorator and a body string on one function must name the same thing. Remove one of the conflicting sources.
#KR7171
@host on a component
Host code runs in the native process and is called from the UI as an async function. A component renders UI, so it cannot be host code. Keep the component in the webview and move the native work into a plain function marked @host that the component calls. For work that only needs to happen at build time, use @server.
#KR7172
Inline host function captures component state
An @host function declared inside a component module is moved to the host process, so it cannot see the component's local variables, signals or props. It may use its own parameters, module-level imports, module-level host declarations and globals. Pass the value as an argument instead. The check covers identifiers declared inside an enclosing function; module-level non-host declarations are not checked.
#KR7173
Host code in a web build
@host markers, .host.ts files, hostFunctions and hostDirs only mean something in a native build, where host code runs in the native process. A web build has no such process, so the marker would be silently ignored and the code would run in the browser or not at all. Remove the marker, or build with krate native.
#KR7174
Request-time rendering in a native build
A native build has no server: every route is prerendered. ssr.streaming, ppr, and page exports such as dynamic = "force-dynamic", revalidate = N or config = { ssr / isr / streaming } ask for rendering per request. Remove them, and load per-request data from host code (@host functions) at runtime.
#KR7175
API route in a native build
A native app has no HTTP server, so routes under src/api have nothing to serve them. Move the logic into host code (a .go file or an @host function) and call it from the UI.
#KR7176
Middleware in a native build
middleware.ts runs in front of a server's requests. A native app has no server, so it would never run. Remove it, and do the check in host code or in the UI.
#KR7177
Runtime component in a native build
@runtime components render per request in a server sidecar. A native build renders every route once, ahead of time. Use @server for build-time rendering, or a client component that loads its data from host code. This covers @runtime, // @runtime, .runtime files, and the runtimeComponents and runtimeDirs config entries.
#KR7178
Server action in a native build
"use server" actions are POSTed to a server. A native app has no server; call an @host function (or a Go function) from the UI instead.
#KR7180
Go function signature cannot be a host call
A UI file imports an exported Go function and calls it as an async function. The bridge supports an optional first parameter ctx krate.Ctx, then the arguments, and one of these result shapes: nothing, error, T, (T, error), <-chan T or (<-chan T, error). A channel result makes the call a stream. Variadic functions, generic functions, a first parameter of context.Context (use krate.Ctx), krate.Ctx anywhere but first, send-only channels, and more than one non-error result are rejected. Change the signature, or wrap the function in one that has a supported shape.
#KR7181
Go type has no wire mapping
Values cross the host boundary through generated encoders without reflection, so every parameter, result and field type must map to a wire type. Supported: bool, string, all int, uint and float kinds, time.Time (a Date), []byte (a Uint8Array), structs, slices and arrays, map[string]T (also string-kinded named keys), pointers (T | null) and named types of these. Rejected: any and other interfaces, channels and funcs inside values, complex numbers, uintptr, unsafe pointers, maps with non-string keys, embedded pointers, and unexported named types (the generated glue lives in another package and cannot name them). The message gives the path to the offending parameter or field. Replace the type with a concrete one.
#KR7182
Go package could not be loaded
The compiler type-checks the Go package behind a .go import with the Go toolchain (go list -export) and the standard go/types package. It failed: the go command is missing, the project has no go.mod, the package has compile errors, or it is package main. Fix the error shown, and check that go build ./... works in the project.
#KR7183
Import from a .go file is not host code
In a native build a UI import from a .go file must name either a Go component (a function in a *.server.go / *.runtime.go file or marked //krate:component) or exported host code: a function with a supported signature, or a package-level variable created with krate.NewSignal. Types, constants, other variables, methods and unexported or missing names cannot be imported. Export a function that returns the value instead.
#KR7184
Go type has a custom marshaler
A type with MarshalJSON, UnmarshalJSON, MarshalText or UnmarshalText encodes itself in a way the generated encoders cannot know, and they do not call encoding/json. Types such as big.Int, netip.Addr or uuid.UUID fall in this group. Convert the value to a plain type (a string, a number or a struct) in the exported function.
#KR7185
Go import has no valid module id or output location
Each .go file imported by the UI gets a module id: its path relative to the project root without the extension (src/lib/tasks.go becomes src/lib/tasks), and host calls are named <module id>.<Name>. The file must exist inside the project, be a non-test .go file, and belong to the project's Go module, and the generated output directory must be inside that module so the glue can import the package.
#KR7190
Host function parameter cannot cross the boundary
Arguments and results of a host function travel between the webview and the native process as data: strings, numbers, booleans, null, arrays, plain objects, Date, Map, Set and bytes. A parameter typed as a function, as a class you declared, or as a DOM type (HTMLElement, Node, Event and friends) can never be sent, so the call would fail at run time. Pass the plain data you need from it instead, for example the element's value or an id. The check only reads explicit parameter annotations and stays silent when it is not sure.
#KR7191
Inline host function cannot be split out
An @host function inside a UI module is moved into the host bundle and replaced by a stub in the UI. That needs a name to register and call it by, so an anonymous default export cannot be split. Give the function a name, or move it to a .host.ts module.
#KR7192
Host code failed to bundle
The host entry and the host modules it imports are bundled into one ES2020 script for the embedded host runtime. The bundler reported an error, usually an import that cannot be resolved, a syntax error, or syntax the bundle cannot express (top-level await in a script bundle).
#KR7193
Host code uses an API the embedded runtime lacks
Host code runs on an embedded JavaScript runtime (QuickJS) by default. It has the ECMAScript built-ins and a small set of web APIs, but no Node built-in modules and no DOM. The build found a reference to an API the runtime does not provide, so the call would throw. Implement the work as a Go host function, or run the module on a full runtime with native.host.islands. A reference inside a feature check such as typeof X !== "undefined" is not reported.
#KR7195
Import is not exported by the host module
UI code imports a name from a host module, but the module has no such export (or the export is marked for another tier). The stub that replaces the host module in the UI bundle only has the module's real exports, so the import would be undefined at run time.
#KR7196
Host export is not callable from the UI
The UI can call host functions and read host signals. An export that is a plain value (a number, string, object or class) has no meaning across the boundary because the UI would get a copy that never changes. Export a function that returns the value, or a hostSignal() for a value that changes.
#KR7200
@krate/app is not installed
A native app's UI calls host code through generated stubs, and the stubs import @krate/app (the host call client). The package is not resolvable from the project. Install it next to @krate/core: npm i @krate/app.
#KR7201
Namespace import of a .go file
The compiler generates a binding for each name a UI file imports from a .go file, so it has to see the names. import * as tasks from "./tasks.go" and export * from "./tasks.go" hide them. Import the functions and signals by name: import { List, Count } from "./tasks.go".
#KR7202
Go module cannot build the Go host
The Go host binary is built inside the project's own Go module, next to the generated glue, so the module has to exist (go.mod at the project root) and require github.com/kratejs/krate/packages/native. Run go get github.com/kratejs/krate/packages/native in the project, or krate native init --go in an empty directory to get a working go.mod.
#KR7203
Go host failed to compile
go build failed for the generated Go host program. The output of the Go command is shown. The packages the UI imports must compile for the target platform; check build constraints and cgo use when you build with --target for another operating system.
#KR7204
Unknown native build target
krate native build --target takes <os>/<arch> where os is windows, linux or darwin (macos is accepted) and arch is amd64 or arm64, for example --target linux/arm64.
#KR7205
krate native init cannot write its files
krate native init creates a small app in a directory. It refuses to overwrite an existing file, so run it in an empty directory or remove the files it names.
#KR7210
Code uses an SDK permission that native.permissions does not allow
A native build works out the SDK permissions the app needs from the code (imports from @krate/app/<area> in UI and TypeScript host code, and krate/<area>.<op> ids) and writes them to app.json. native.permissions is an allowlist: when it is set, every permission the code needs must be listed there (fs also covers fs:read). The message names the import site and the permission. Add the permission to native.permissions, or remove the call.
#KR7211
Release executable failed to compile
krate native build --release links the platform layer, the SDK, the app's Go host code and the UI assets into one executable with go build. The output of the Go command is shown. Check that the Go host packages compile for the target (CGO_ENABLED=0, so cgo packages cannot be used), and run go mod tidy in the project.
#KR7212
The Go toolchain is required
Apps with Go host code always need go on PATH to build, and native.release.compile: "always" asks for a compiled release executable. Install Go (the version in the native module's go.mod), or for an app without Go host code set native.release.compile to "auto" or "never" to get the prebuilt-shell layout (dist-native/app next to krate-shell).
#KR7213
Cannot determine the native module version
A release build of an app without Go code generates a small Go module that requires github.com/kratejs/krate/packages/native. Outside the Krate monorepo it needs the module version that matches this compiler. A development build of the compiler has none: set KRATE_NATIVE_VERSION (for example v0.5.0), or build from a release of krate.
#KR7214
krate native profile cannot collect a profile
krate native profile builds the app (a release executable when Go is available), runs it with KRATE_CPUPROFILE set and copies the profile to native.release.pgo when the app exits. The message says which step failed: the app produced no profile (it must exit normally, for example by closing its window or sending SIGINT), or the profile could not be copied.
#KR7220
Nothing to package
krate native package packages a built app. It looks in dist-native/<os>-<arch>/ for a release executable (krate native build --release), and falls back to the prebuilt-shell layout (dist-native/krate-shell next to dist-native/app/, from krate native build --shell auto). Build first, or pass --target <os>/<arch> to package a different platform's output.
#KR7221
A packaging tool is not installed
Most formats are written by the compiler itself (zip, tar.gz, .deb, .rpm, MSIX, .app). Some need a platform tool that cannot be replaced: makensis for an NSIS installer, appimagetool for an AppImage, hdiutil (macOS only) for a .dmg. Install the tool or pick another format with --format. On macOS without hdiutil the .app is delivered as a .zip.
#KR7222
Unknown or unsupported package format
Formats by platform: macOS app, zip, dmg, mas; Windows zip, nsis, msix, msix-store; Linux tar.gz, deb, rpm, appimage, flatpak, snap. native.bundle.windows.installer takes msix or nsis; native.bundle.linux.formats takes deb, rpm, appimage, flatpak and snap.
#KR7223
Application icon cannot be used
native.icons must name a PNG (or JPEG) file of at least 256x256 pixels; 1024x1024 gives sharp icons on every platform. The packager makes .icns, .ico and PNG sizes from it. Without native.icons a placeholder icon is generated.
#KR7224
Signing tool not available
macOS signing needs codesign and runs on macOS only. Windows signing needs signtool (on Windows) or osslsigncode (anywhere). Linux package signatures need gpg. Sign on a machine that has the tool, or skip signing for development builds.
#KR7225
Signing or notarization failed
The signing tool exited with an error; its output is shown with secrets removed. Common causes: the identity is not in the keychain, the certificate expired, the timestamp server is unreachable, or Apple rejected the submission (run xcrun notarytool log <id>).
#KR7226
Notarization credentials missing
krate native notarize needs credentials: a keychain profile (--keychain-profile or KRATE_NOTARY_PROFILE, created with xcrun notarytool store-credentials), or an App Store Connect API key (KRATE_NOTARY_KEY file path, KRATE_NOTARY_KEY_ID, KRATE_NOTARY_ISSUER), or an Apple ID (KRATE_NOTARY_APPLE_ID, KRATE_NOTARY_TEAM_ID, KRATE_NOTARY_PASSWORD app-specific password). Prefer the profile or API key: a password on the command line is visible to other users.
#KR7227
Updater signing key missing or invalid
Update files are signed with an Ed25519 key. krate native keygen creates the pair; put the public key in native.updater.publicKey and give the private key to krate native package as KRATE_UPDATER_PRIVATE_KEY (the base64 text) or KRATE_UPDATER_PRIVATE_KEY_FILE (a path). The private key must match the public key in the config.
#KR7228
Writing a package failed
A package file or its staging directory could not be written. The message names the path and the operating system error.
#KR7229
App metadata cannot be packaged
Packaging needs native.appId (reverse-DNS), native.productName and a semantic native.version; a MSIX package also needs native.bundle.windows.publisher. The message names the field and the value that was rejected.
#KR7230
Host code imports a Node built-in on the QuickJS runtime
Host code runs on an embedded QuickJS runtime by default. It has the ECMAScript built-ins and a small set of web APIs, but no Node built-in modules, so an import of node:fs, node:path or any other built-in cannot work and the build refuses it. Run the host code on a full runtime with native.host.runtime set to "node", "bun" or "deno", or run only the module (or package) that needs the built-in there with native.host.islands, for example { "sharp": "node" }. Go host functions are the third option.
#KR7231
Host export reaches islands of different runtimes
native.host.islands assigns a package or path to a runtime, and a registered host export runs wherever the modules it imports run. When one export imports modules assigned to two different runtimes there is no process that can run it. Split the export so that each part imports one island, or move both modules to the same runtime.
#KR7232
An islands entry matches no host code
An entry of native.host.islands names a package or path that no registered host export imports, so it changes nothing. Package names must match the import specifier's package (sharp, @scope/name); paths are relative to the project root and may use * and **.
#KR7233
Host runtime not found or wrong version
A host child needs its runtime (Node, Bun or Deno): on PATH for development, or to build the executable that ships with the app. The runtime was not found, or its version does not match native.host.version. Install it, point KRATE_NODE, KRATE_BUN or KRATE_DENO at a binary, or change the pinned version. Release builds require native.host.bundle to be true.
#KR7234
Compiling the host child failed
A release build turns each host child into a self-contained executable: a Node single executable application, bun build --compile, or deno compile. The tool failed; its output is in the message. Cross-compiling needs the target's runtime, which the tool downloads or you provide with KRATE_NODE_<OS>_<ARCH>.
#KR7235
scriptc cannot compile this host code
With native.host.runtime set to "scriptc" the host code is compiled to a native executable that has no JavaScript engine, so code scriptc rejects fails the build; there is no fallback to an interpreter. The message carries scriptc's own diagnostic code (SC####) and hint. Rewrite the code as the hint suggests, move it to a Go host function, or run it on QuickJS or Node. krate native check --scriptc reports these without building.
#KR7236
scriptc or its toolchain is missing
scriptc is not on PATH, or the linker it needs to build an executable is missing: clang on macOS and glibc Linux, zig on Windows and musl Linux and for cross-compiling. Install scriptc (npm install -g scriptc, Node 24 or later) and the linker, or use another host runtime.
#KR7237
scriptc rejects the Krate host child runtime
The host code compiled, but scriptc rejected a line of the Krate host child runtime (packages/native/hostchild) that serves the call protocol. This is a limitation of the installed scriptc version, not of your code. Update scriptc, or use another host runtime.
#KR7240
Build function called with non-literal arguments
A function marked @build (TypeScript) or //krate:build (Go) runs once during the native build and its result is baked into the app, so the compiler has to know every argument tuple while it builds. Only literal arguments are supported: strings, numbers, booleans, null, and arrays and objects of those. Each distinct call with literal arguments gets its own baked value. Pass a literal, or drop @build and call the function as an ordinary host function at run time.
#KR7241
Build function used without being called
A build function is replaced by its baked values, which are looked up by the literal arguments of each call. Passing the function around, aliasing it, importing it as a namespace or re-exporting it hides the calls from the compiler. Call it directly where its value is needed: const v = appVersion().
#KR7242
Build function failed
A build function threw, rejected, never settled or returned an error while the native build ran it. TypeScript build functions run in a bare JavaScript VM without fetch, timers, the file system or locale-dependent methods; imports they use must be plain code. Fix the error shown, or remove the build marker if the function needs those capabilities at run time.
#KR7243
Build function result cannot be baked
The value a build function returned is embedded in the app, so it has to be plain data: strings, finite numbers, booleans, null, arrays and plain objects, at most 8 MiB of JSON, nested at most 512 levels, with arrays of at most 1,000,000 elements. NaN, Infinity, cycles, functions, symbols, bigint, Date, Map, Set, binary data, class instances and unsettled promises are refused. Convert the value to plain data inside the function.
#KR7244
Build marker on something that cannot be baked
@build and //krate:build apply to ordinary functions that return one value. They cannot mark components, generators or streams, signals, or functions that return a channel.
#KR7245
Go build functions could not be evaluated
//krate:build functions are evaluated by compiling and running a small generated Go program in the project's Go module, so the Go toolchain has to be installed and the host packages must compile. The output of the Go command is shown.
#KR7250
Plugin has no krate-plugin.json
Every entry of native.plugins names a directory, an npm package or a Go module that contains a krate-plugin.json next to its Go package. The compiler could not find one at the resolved location. Check the path or package name, install the package (npm i), or create the manifest with krate native plugin init <name>.
#KR7251
Invalid plugin manifest
krate-plugin.json must be valid JSON with a name (lowercase words joined by hyphens, 2 to 40 characters), a go import path, optional version, krate (the minimum Krate version), ts, permissions (a list of {name, description}) and ops (a list of {name, go, permission, manual}). Op names are lowerCamel like the SDK ops (info, cpuLoad; the Go function is the name with its first letter upper-cased, or the op's go field); permission names are lowerCamel too, and an op's permission must be one the manifest declares. The message names the field.
#KR7252
Duplicate plugin, op or permission
Plugin names, the ops of one plugin and the permissions of one plugin must each be unique, because an op is the host id plugin/<name>.<op> and a permission is plugin:<name>.<permission>. Rename one of the two, or remove the plugin that is listed twice in native.plugins.
#KR7253
Plugin Go import path does not resolve
The go field of krate-plugin.json must be the import path of the plugin's Go package: the module path from the nearest go.mod plus the package's directory inside that module. The plugin also has to live in a Go module (its own go.mod, or the app's). For a go: plugin the module has to be downloadable (go mod download); give the version after an @ or require it in the app's go.mod.
#KR7254
Plugin needs a newer Krate
The plugin's krate field names the oldest Krate version it works with, and this compiler is older. Upgrade Krate (npm i @krate/core@latest) or use an older release of the plugin.
#KR7255
Unknown or disallowed plugin permission
A plugin permission is written plugin:<plugin>.<permission> and has to be declared by an enabled plugin. It appears in native.permissions or native.window.permissions without such a plugin or declaration. A build derives the plugin permissions the code needs; list them in native.permissions only to restrict the app.
#KR7256
Could not build the shell for the app's plugins
An app with native plugins runs under a shell that is built for it with the Go toolchain, because plugins are Go code linked into the shell process. The Go command failed or is missing. The output of go build is shown; the plugin's package has to compile for the target with CGO_ENABLED=0, and its module has to be resolvable (go mod download).
#KR7257
Plugin op cannot be bound
Each op in krate-plugin.json (not marked manual) must be an exported function or an exported *krate.Signal[T] variable of the plugin's Go package, with a signature the host-call bindings support (see Go host code). The Go error is shown with the position in the plugin.
#KR7270
Image much larger than its rendered size
An <img> has literal width/height (or an inline style size) that is several times smaller than the image file's pixel size. The webview decodes the whole bitmap and keeps it in memory, so a 2000 px photo shown at 100 px costs about 16 MB of decoded pixels for a 100 px picture. Resize the file to at most about twice its rendered size (the factor is native.lean.imageRatio, default 2). The check only runs when the file is a local PNG, JPEG, GIF or WebP and the rendered size is a literal.
#KR7271
Large data: URL inlined into code or CSS
A base64 data: URL above the threshold (native.lean.dataUriKb, default 16 KiB) sits in a source or stylesheet file. It is parsed with the page, kept as a string, and decoded again for each use, so the bytes cost memory more than once. Put the asset in the public directory and reference it by URL; the shell serves it from the app bundle and the webview decodes it once.
#KR7272
Web font where a system font stack would do
The project loads a web font (an @font-face rule with a font file, a Google Fonts or other font-service link, or an @fontsource import). Each family and weight costs the file, a parsed copy and shaped glyph caches in the web process. Icon fonts are not reported. This is a heuristic, not a measurement: it cannot know whether the design needs the typeface. Prefer system-ui, -apple-system, "Segoe UI", sans-serif, and keep a web font only when the brand needs it (silence this with native.lean.ignore: ["KR7272"]).
#KR7273
CSS effect that forces compositing layers
backdrop-filter, a large filter: blur() (16 px or more) or a blur in an animated rule, a very large box-shadow on a tag or universal selector, and will-change on many elements each give the element its own GPU layer with its own backing store, and a backdrop-filter also needs the content behind it re-rendered. Layers are memory in the GPU process. Use them on a few elements at most, drop them from lists and repeated components, or use a solid or semi-transparent background instead.
#KR7274
Long list rendered without windowing
A .map() renders a JSX element per item over an array with more than native.lean.listItems entries (default 100) known at build time, or over a value from host code, whose length the UI does not bound, and the file uses no windowing component or .slice(). Every item stays in the DOM, so memory grows with the list. Render only the visible window (a virtual list component), page the data with .slice(), or have host code return one page at a time.
#KR7290
Media or location used without a macOS usage description
The UI code calls getUserMedia, getDisplayMedia or navigator.geolocation, and native.media.usage has no sentence for it. macOS ends a process that touches the camera, microphone or location when its Info.plist lacks NSCameraUsageDescription, NSMicrophoneUsageDescription or NSLocationUsageDescription, and it shows that sentence in its consent prompt. Packaging writes a generic sentence so the app does not crash, but a prompt that says why the app needs the device gets more yeses. Set native.media.usage.camera, .microphone, .location or .screenCapture. The check runs for builds that target macOS and only when the scan of the built UI finds the call; an API name built at run time is not found.
#KR7300
Cannot merge a macOS universal app
--arch universal (or --target darwin/universal) merges a darwin/arm64 build and a darwin/amd64 build into one .app: the executable and every Mach-O file the two builds share (Go host children, compiled Node, Bun and Deno hosts) become universal files. Both builds must exist and must contain the same files. Build both with krate native build --release --arch universal. A host runtime tool that cannot produce the other architecture needs to be built on a machine that can, or switched off for the universal app.
#KR7301
Store build configuration problem
A Mac App Store build (--target mas) needs native.bundle.macos.mas.teamId and a provisioning profile; a Microsoft Store build (--format msix-store) needs native.bundle.windows.store.identityName, publisherId and publisherDisplayName exactly as Partner Center shows them. The message names the field and the rule.
#KR7302
Flatpak or Snap package cannot be generated
The Flatpak manifest, AppStream metadata and snapcraft.yaml are generated from native.* values; a value that breaks the format (an invalid license expression, a Flatpak runtime version that is not a number, an unknown Snap grade) is reported with the field and a hint.
#KR8xxx: islands, compiled packages and general React compatibility
#KR8001
React API removed in React 19
The code uses an API that React 19 removed: findDOMNode, ReactDOM.render, ReactDOM.hydrate, unmountComponentAtNode, createFactory or propTypes checking. Krate follows React 19 semantics, so these have no equivalent. Use a ref instead of findDOMNode, and let Krate mount pages instead of calling render or hydrate yourself.
#KR8002
React API not supported in source components
A React API used in a source component has no lowering to Krate signals, so the component would render differently from React. Rewrite the component with a supported pattern (see the React compatibility guide), or move it into a compiled React package so it runs as an island with full React semantics.
#KR8003
Component renders nothing because it could not be compiled
Krate could not compile a component (for example an unresolved component name or an unsupported class feature) and emitted an empty placeholder where React would render content. Fix the reported cause; the placeholder is never a valid substitute for the component's output.
#KR8004
Context consumer child is not a single render function
<Ctx.Consumer> renders the result of calling its child with the nearest provider value, so its only child must be one function such as {(value) => <span>{value}</span>}. Krate inlines that function at build time; it also needs a plain parameter (or a { a, b } pattern without renames or defaults). Read the value with useContext(Ctx) in a component when the render function is more involved.
#KR8005
Legacy context API
A class component uses legacy context (contextTypes, childContextTypes or getChildContext). React 19 removed it, and Krate does not pass legacy context: this.context is empty. Create a context with createContext, provide it with <Ctx value={...}> and read it with static contextType = Ctx or useContext(Ctx).
#KR8006
Portal container cannot be resolved
createPortal(children, container) moves its children into a DOM node after hydration. Krate resolves document.body, document.getElementById("id") and document.querySelector("selector") with literal arguments, and any other expression in the hydration scope of a client component; elsewhere the content mounts into document.body, and a container that is not an element when the page hydrates keeps the content unmounted. Make sure the container exists before the component hydrates (for example a <div id="modal-root"> in the layout).
#KR8007
Same-file component inside an island
An external package island contains a component declared in the page module. The page component belongs to the Krate runtime and cannot run inside the island's Preact tree. Move the component into its own module and import it, or render it outside the island.
#KR8008
Island stays client-only
The island has no build-time props, uses a browser-only API, or could not be rendered by Preact during the build. Its placeholder is emitted without server-rendered markup and the client mounts it after the island chunk loads. Pass build-time initial values or keep the island client-only intentionally.
#KR8009
Island asset could not be built
Krate could not bundle the island's external package, local module, Preact dependency, or generated chunk. Check the reported resolver error and install the missing package (Preact 10.20 or newer) in the project.
#KR8010
createPortal is not in a child position
Krate lowers createPortal(children, container) when it is a child ({createPortal(...)}) or a branch of a conditional child ({open && createPortal(...)}, {open ? createPortal(...) : null}). Anywhere else the call is left as is and fails in the browser because createPortal is not a global. Render the portal as a child, or use <Portal container={...}>.
#KR8011
Expression has no build-time value and no client binding
The compiler could not compute the value of this expression while building the page (it calls a function it cannot see into, reads an unsupported built-in, or depends on data that only exists at runtime) and the component has no client code that could fill it in, so the page renders it as empty text. Move the value into component state or an effect, compute it from values the build can see, or make the component interactive so the browser evaluates it.
#KR8012
Client directive on a component that is not an island
client:visible, client:idle and client:load choose when an island mounts, and only apply to the root tag of a compiled package component (or a module that uses a React library) rendered as an island. On a Krate component or an HTML element they do nothing; Krate hydrates those with the page. Remove the directive, or put it on the package component itself.
#KR8013
React library component or hook used where no island can run it
A component calls a hook of an npm React library (zustand, react-hook-form, swr, @tanstack/react-query, ...), or a static layout renders a compiled React component. Those need React's render model, which Krate's lowered components do not have, so Krate runs them on Preact: as an island in a page, and as a client boundary in a server-rendered page, layout or component (icons and other components without state render to plain HTML). A hook cannot be called from a server component: add "use client" to the module that calls it, or replace the library with createSignal / createResource. A layout that is baked into the static shell cannot host compiled components: make it async so it renders per request, or render them from a page.
#KR8014
css prop is emotion's, not a DOM attribute
A css={...} prop on a DOM element is understood only by emotion's JSX runtime. In a module that does not use it Krate renders css as a plain attribute, so the styles are lost. Add /** @jsxImportSource @emotion/react */ to the top of the file so the module runs as a Preact island with emotion, or use CSS modules, Tailwind or a stylesheet.
#KR8015
Layout provider cannot reach the islands of its pages
A layout wraps {children} in a component of a React library (a QueryClientProvider, a ThemeProvider, a Redux Provider). Islands run in Preact, so the layout cannot give them context. Krate lifts such wrappers into a module every island of the page renders inside, but only when their props can be computed without the layout's own state: constants, imports, module-level values, and useState(() => value) or useMemo(() => value, []) with no setter in use. A prop that reads the layout's params, a signal or a state setter cannot be lifted. Build the value from constants, or wrap the island's own module in the provider.
#KR8016
Layout provider renders markup around its children
A component a layout wraps around {children} renders elements of its own, so it is not a context provider that can be moved into the islands: Krate renders the page content, and an island cannot sit inside markup that belongs to the layout. The layout keeps the component as it was and the islands of its pages do not see its context. Split the component into a provider that renders only its children and the markup, or put the provider inside the island's own module. A provider that adds only <script> elements next to its children (next-themes) is lifted.
#KR8017
Module state is not shared between Preact and real-React islands
Preact islands and real-React islands (those that use a library built on react-reconciler, such as @react-three/fiber) are bundled separately, because react means preact/compat in one and the project's React in the other. A module both reach that does not depend on React is bundled once into a shared chunk, so both see one instance. A module that imports React, directly or through its imports, needs a copy for each; the message names the import chain that reaches React (src/a.ts -> src/b.ts -> "react"). This module also declares module-level state (a let or var, an object made with new, or a store such as zustand's create), so the two copies keep separate state: a cache fills twice, a store has two values. Move the state into a module that does not import React, for example a store made with zustand/vanilla that a hook module wraps. This is a warning.
#KR8030
Higher-order component cannot be resolved at build time
const Page = withX(Inner) (or export default withX(Inner)) is compiled by inlining the component function that withX returns, with its parameters replaced by the arguments. That works when withX is a function in the project whose body holds only that returned component function. A wrapper imported from a package, or one with other statements around the returned function, cannot be inlined, so the component would render nothing; the build fails instead. Declare the wrapper in your source as function withX(C) { return function Wrapped(props) { return <C {...props} /> } }, or write the wrapped component out by hand.
#KR8031
Prop of Activity, ViewTransition or SuspenseList is not supported
<Activity> supports mode="visible" and mode="hidden". <ViewTransition> supports name, default, enter, exit, update and share as strings, and ignores the event callbacks (onEnter, onExit, onUpdate, onShare). <SuspenseList> renders its children and ignores revealOrder and tail. Other props have no effect and are reported once per element. This is a warning: the children always render.
#KR8301
Render value keeps its first value
React recomputes every value in a component body on each render. Krate compiles a body value that reads state, props, context or a custom hook result into a derived value that is recomputed when its inputs change. This value could not be compiled that way: it is reassigned inside a closure (an event handler or effect), or by a body statement that also writes another variable, or it is read between the statements that build it. It keeps the value it had when the component hydrated. Compute it in a single expression (const label = n > 1 ? "items" : "item"), or keep the changing value in state.
#KR8302
Imported value is not available to hydration code
Hydration code (an event handler, effect, derived value, text binding or a module-level initializer) uses a binding imported from another local module, and the compiler could not copy that module's declaration into the page's hydration script. Functions, classes, constants, lowered namespaces, namespace imports and JSON, ?raw and ?url imports are copied; npm packages are bundled for the browser. A binding created by a destructuring export, or one that only a side effect initializes, cannot be copied, so at runtime the name would be undefined. Export it as a function, class or plain const, or define it in the component's module.
#KR8310
Environment variable is not exposed to client code
Client code and statically rendered pages cannot read process.env or import.meta.env values: they are build and server-time only and are never written into HTML or JavaScript. The read yields undefined. Name the variable with the KRATE_PUBLIC_ prefix (KRATE_PUBLIC_API_URL) to inline its value at build time, or read it in a server component, API route or server action instead. import.meta.env.MODE, DEV, PROD, BASE_URL and SSR are always available.
#KR8320
Element type is not known at build time
<Tag> where Tag is a variable (const Tag = as || "div", a prop, a value read from state) is rendered as the element it names. The build resolves it when the variable folds to one tag name: a string constant, a prop the caller passes or its default, or a condition on those. This one does not, for example because it depends on a signal or on a value only known at request time, and the page would otherwise contain an empty placeholder instead of the element and its children, so the build fails. Pass the tag as a string the build can see, render each case as its own element ({wide ? <section>...</section> : <div>...</div>}), or move the component to a *.runtime.tsx file to choose the tag per request.
#KR8321
Member tag does not resolve to a component
<ui.Button> names the export Button of a namespace import (import * as ui from "./ui"), of a re-exported namespace (export * as ui from "./ui"), or a member of an object. The build follows namespace imports through barrel files (export { Button } from "./Button", export * from "./Button") to the function component the member names. This tag matched none: the module exports no such member, the member is not a function component (a string, a class that is not lowered, a value built at run time), or the object it reads from is not a namespace of project modules. Rendering nothing would drop the element and its children, so the build fails. Check the member's spelling and export, import the component by name, or declare it as a function.
#KR8322
Module value changed by top-level code cannot be evaluated at build time
A module-level value that later top-level code changes (const items = [] followed by for (...) items.push(x), an assignment, a property write, Object.assign, or a call to a function of the module that does one of these) is evaluated at build time by running that code in order. When a statement cannot be run there (it reads the browser, the clock, an imported function or anything else unknown), the value stays unknown rather than keeping its initial value. A component that hydrates reads it at run time. A component rendered at build time has no run time, so the build fails. Make the top-level code plain, compute the value in one expression, or move the reading component to one with client state.
#KR8323
Children with client state rendered more than once
A component that renders {children} in several places mounts one instance of the children for each place, and the build gives each instance its own hydration keys. That works for up to 8 placeholders written out in the component body. When the placeholder sits in a loop or an array callback (items.map(() => <li>{children}</li>)), or there are more than 8, the copies share one set of keys, so state, event handlers and bindings in the children only work for one of them. Render a component per item that owns its state, pass the data instead of children, or move the state up out of the children.
#KR8330
CSS scope handle is read by code that runs in the browser
A CSS scope handle (const tab = createCSSChoice(...)) is a build-time value: the compiler turns tab.trigger(), tab.panel(), tab.close() and tab.current() spreads into labels, panel classes and CSS, and nothing of the handle exists in the browser. Passing it as a prop works when the receiving component only uses those helpers in its JSX, at any depth. This component reads the handle some other way (in an event handler, an effect, a computed value or a call to another function), or it was passed to an external island, so the read would fail in the browser. Use the helpers in the JSX of the component that receives the handle, or pass the getter and setter values (const [tab, setTab] = createCSSChoice(...)) to a component with its own client state, or use createSignal.
#KR8331
CSS signal value passed to a component that renders at build time
The state of a CSS signal lives in the page (hidden inputs and :has() selectors), so no value exists at build time. A component without client state is rendered to static HTML during the build, which makes a CSS signal getter or setter passed to it unreadable: props.tab() has nothing to return. Pass the scope handle instead (const tab = createCSSChoice(...), <Child scope={tab} />) and use props.scope.current(), props.scope.panel() or props.scope.trigger() in the child, or give the child its own state with createSignal.
#KR8350
outDir would delete project sources
The build empties outDir before it writes the site, and krate clean deletes it. An outDir that is, or contains, the project root, the pages directory or the public directory (outDir: "..", ".", "src") would delete the project's own files, so the build stops before anything is removed. Point outDir at a dedicated directory such as dist; a directory outside the project that holds none of your sources, such as ../site-dist, is fine. Setting KRATE_ALLOW_UNSAFE_OUTDIR=1 skips this check.
#KR8351
Trigger and content do not share a value
Dialog, Sheet, Popover, DropdownMenu and the other widgets built on a CSS-signal scope connect a trigger to its content by value: <Dialog.Trigger value="a"> opens <Dialog.Content value="a">. A trigger and a content that both leave value off are paired with each other (the value is on). This one has no value, but the widget has no part without a value to answer it (every content has a value, or every trigger does), so it would never open or show anything. Give the trigger and the content the same value, or remove it from both.
#KR8352
Value needed at build time is unknown
A component without state (no createSignal, useState or other hook that holds state) is rendered to static HTML while the site is built, so every value it renders has to be known then: a prop, a local variable, or a module constant. This expression is none of those, for example it names an identifier that is not defined where the component renders (unresolved identifier x), reads the clock or the browser, or calls a function the build cannot run. A constant that holds JSX (an array of sections whose body is a fragment) is known, and so is JSX passed as a prop: both are rendered to HTML at build time. There is no run time to fall back on, so the build fails instead of printing a guess. Define or import the name, pass the value as a prop, or give the component state so it hydrates in the browser. A value that differs per request belongs in a *.runtime.tsx component.
#KR8353
Head value cannot be evaluated at build time
Tags inside <Head> (and <title>, <meta> and <link> rendered on their own) are written into the static HTML so crawlers and link previews see them. A call to an imported helper is evaluated at build time when it is plain code: string and template work, JSON, URL, encodeURIComponent, and calls to other functions of your project. This value is none of those (it reads the browser, the clock, process.env, an object built by a class, or something else the build cannot run), so the tag would only be completed in the browser and crawlers would see it empty. Compute it from plain values, pass it as a prop, or move the tag to a page whose metadata comes from generateMetadata.
#KR8354
Component with state in a prop is rendered twice
A prop that holds JSX with a component that has state (slot={<Probe />}, where Probe uses createSignal or useState) is one component instance. The receiving component reads the prop in more than one place, but the instance can only be mounted in one of them, so the other copy shows the server markup without ever hydrating. Render the prop in one place, or give each place its own element (a separate prop for each place).
#KR8360
Component state resets when the condition flips
cond ? <Form mode="edit" /> : <Form mode="new" /> renders the same component type at the same position. React keeps that instance when cond flips, so its state, effects and refs survive, and Krate does the same by lowering the pair to one element with conditional props (<Form mode={cond ? "edit" : "new"} />). A few shapes cannot be lowered that way: a render-prop function as children, a spread whose position differs between the branches, a ref that differs, a condition with side effects, a lazy component, or an external island. For those the branch that is shown is mounted and the other is unmounted, so flipping the condition restarts the component with fresh state and runs its cleanups and mount effects again. Render one element and pass the differing values as props, make both branches the same shape, or give the branches different key props when the restart is what you want (different keys never warn).
#KR8601
Unsupported page segment export value
Krate reads the Next.js-style page exports export const revalidate (a constant number of seconds, 0 for per-request rendering, or false to cache indefinitely) and export const dynamic ("auto", "force-dynamic", "force-static" or "error") at build time. The value could not be read statically or is not one of the supported values, so it is ignored. Write a literal value. The same code covers export const maxDuration in an API route, which must be a constant positive whole number of seconds (at most 3600); otherwise the route keeps the default API timeout.
#KR8602
Static page reads revalidating data
The page reads data with cache tags, a revalidate window or cache: "no-store", but it is rendered statically (it is pinned with dynamic = "force-static", revalidate = false, or the project uses output: "static"). Static HTML is baked once at build time: revalidateTag, revalidatePath and revalidate windows cannot refresh it. Remove the static pin or export revalidate = N so the page is served with ISR.
#KR8603
revalidatePath targets a static page
A revalidatePath() call names a route that is rendered statically (SSG). The page's HTML is a file baked at build time, so revalidation cannot rebuild it: at runtime the call reports the route under skipped and logs a warning. Make the target page ISR (export const revalidate = N) or SSR (export const dynamic = "force-dynamic"), or rebuild the site to refresh it.
#KR8604
forbidden() or unauthorized() never runs per request
forbidden() and unauthorized() answer one request with a 403 or 401 page, so they only work in code that runs on every request: a page rendered with ssr, isr or streaming, an async server component, a server action or an API route. This call sits in a statically built page, or in a layout (layouts are baked into the shell at build time), so it never runs and the page is served to everyone. Make the page request-time (export const dynamic = "force-dynamic"), or call the function from an async server component that the page renders.
#KR8801
Image source cannot be used
An <Image> is optimised while the site is built, so its src must name an image file that exists (a path starting with / is relative to the public directory) and can be decoded. Krate reports the problem as a build error instead of shipping a broken image. Fix the path or the file.
#KR8802
Remote image host is not allowed
A remote <Image src="https://..."> is only passed through when its host matches images.remotePatterns in krate.config.ts. Add the host to the allow list, or download the file into the public directory.
#KR8803
Image prop must be known at build time
An <Image> generates its variants during the build, so src, width, height, quality and priority must be literals (or consts initialised with literals) by the time the page is rendered. A value that only exists in the browser cannot be used. alt, sizes and className may be expressions.
#KR8804
Image has no alt text
An <Image> without an alt attribute is announced by screen readers by its file name. Add a description, or alt="" when the image is purely decorative. This is a warning.
#KR8810
Content collection is shipped to the browser
A getCollection("name") chain is normally evaluated while the site is built and only its result is rendered. When the chain depends on a value that only exists in the browser (a signal, an event), the collection has to be evaluated there, so its entries are copied into the page script. The warning names how many entries and about how many bytes are shipped. Krate ships only the fields the page mentions (the body and rendered html only when referenced), but every entry in the collection, drafts included, is still included. Filter with build-time values, or compute the list on the server. A lookup keyed by the route param of a [slug] page folds to that page's entry, whether it is written inline, through a const posts = getCollection(...), with the params destructured, or in a module-level helper that only returns the chain; the fallback page of the route carries only the entries that have no generated page. This is a warning.
#KR8820
Component option value must be a literal
Tabs, Accordion and the other zero-JS components turn each part's value into CSS while the site is built, so every value on their parts must be a string literal in the source. A value read from data (for example value={item.id} inside items.map(...)) cannot be enumerated: the panels for that value get no show/hide rules, defaultValue is ignored and every panel stays visible. Write the values out, or use <Select>/a createSignal based component for data-driven options. This is a warning.
#KR8840
Icon cannot be resolved
An <Icon name="..."> is compiled to inline SVG while the site is built. A name without a colon is a local icon and must exist as icons/<name>.svg in the project; set:name (for example lucide:home) is fetched from the Iconify API and cached under .krate/cache/icons. When neither works the build fails and names the file or lookup that failed, instead of putting an error message in the page. Fix the name, add the file, or pre-populate the cache for offline builds. This is an error.
#KR9xxx: routing, segment pages and rendering errors
#KR9001
Conflicting segment pages
Two files define the same role for one URL directory: 404.tsx and not-found.tsx, error.tsx and 500.tsx, or the same file name in two route groups that resolve to one directory. Krate cannot tell which one to use. Keep one file per role in a directory.
#KR9002
Segment page in an unsupported directory
404.tsx, not-found.tsx, error.tsx and 500.tsx are per-directory segment pages. They cannot live inside a parallel-route @slot or an intercepting (.)route directory, because those render inside their parent's layout. Move the file to the parent route directory.
#KR9003
Error page ignores request-time rendering
An error page (error.tsx, 500.tsx) answers while the app is failing, so it is prerendered once and never depends on the renderer. A request-time mode (ssr, isr, streaming, runtime components, async server components) on it is ignored. Read request data in the page's client code. A not-found, forbidden or unauthorized page (404.tsx, 403.tsx, 401.tsx) can render per request instead.
#See also
Last updated: 2026-11-17
Contributors: Noinkin