Skip to content

Error Codes render

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/render

Part of Error codes: every code @ultimat3/render registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_ASSET_MISSING a page names a site asset the app does not have asset('assets/…') names a file that is not under apps/<app>/site/assets/, or a path outside that tree (.., an unsupported extension). Thrown while the page renders, so x build --target static fails on it asset('logo.svg') naming a file under apps/web/site/assets/ — add the file, or correct the path; then x build --target static. Details: Static Assets
X_BUDGET_EXCEEDED a route blew its JS budget a heavy transitive import x routes --json for the chain; move it behind hydrate: 'interaction' or raise the budget deliberately
X_ISLAND_INVALID an island declaration cannot become a client entry no src, a remote URL, a file not named *.island.tsx, unsafe characters, or two islands on one page claiming the same id. The extension is the rule: a module ships to the browser iff its name says so, so the bundler decides without opening the file rename the module to <name>.island.tsx and point src at it — the cause names the offending value
X_ISLAND_NOT_HYDRATED a page renders an island nothing would boot three causes, and the cause says which. (1) the route states hydrate: 'never' beside an island — a contradiction the author wrote on purpose, since a route carrying one otherwise derives its own. (2) the island() call sits below the defineRoute that drains it, so the declaration had not happened yet. (3) the page was rendered outside a render that collects islands, so no hydration runtime is emitted and the chunk is never requested — this is the host's wiring, not the author's page (1) drop the explicit hydrate: 'never' and let it derive · (2) move the island() call above defineRoute · (3) render through renderToHtml(tree, { islands: islandCollector({ file, hydrate }) }) so the island is counted, booted and budgeted
X_ISLAND_PROPS_INVALID an island was handed props it may not receive a key not listed in props: [...], a value that is not JSON (a function, Date, class instance, bigint, symbol, undefined, or a cycle), or a payload over ISLAND_PROPS_MAX_BYTES (16,384 bytes As of 2026-09-05; it was 4,096). A spread such as <Modal {...row} /> fails and the cause names every undeclared key, which is how a password hash is caught before it crosses to the client. Over the cap, the cause names the heaviest props with their bytes. A declared 500 — the author's fault, never the caller's — so problem+json carries the cause in prod; on a budgeted route the budgets step reports it at verify time under this code declare the prop in island({ props: [...] }), or pass a JSON value; over the cap, pass <prop>: [] and an endpoint (queryPath('<query>'), from @ultimat3/core) and fetch the rows inside the island after mount — a list that is the same on every request is a dataset, not a prop
X_NAVIGATION_MODAL_PATH_INVALID openModal was given something that is not a path of this origin openModal(path) addresses a modal by the hash '#', so path must be an absolute path on this origin starting with a single '/' — a URL of another origin, a protocol-relative '//host' or a relative 'new' names no modal openModal('/runs/new') — the modal route's own path, as its link carries it; never a full URL or a relative one
X_PRERENDER_FAILED a prerendered path threw during build prerender() returned an id that no longer resolves fix the data source, or narrow prerender()
X_ROUTE_DUPLICATE two route files resolve to one URL a copied page directory x routes --json — delete or rename one of the two; the route table is keyed by URL
X_ROUTE_FILE_INVALID a route file is not named for its surface site/pricing.tsx or site/blog/index.tsx instead of <dir>/page.tsx mkdir -p -- '<dir>' && mv -n -- '<file>' '<dir>/page.tsx' — quoted exactly as the thrown fix quotes them, because a route path may hold a space. api/ takes no route file (26.0.0): an action, or a plain HTTP route in the routes runtime override for a wire format an action cannot speak. -n because the correct file may already be there
X_ROUTE_LOAD_FAILED a route's load threw while resolving its data the query, client call or fetch inside load failed; the message names the path fix the load for that path, or return a fallback so the page can still render. An UltimateError thrown by the loader passes through untouched, with its own code
X_ROUTE_LOAD_INVALID a route declared a load that is not a function load: someData instead of load: () => someData load: ({ params, url }) => ({ … }) returning the page data, or remove it
X_ROUTE_META_MISSING required metadata missing no meta.title, or no description on a site/ route meta: () => ({ title, description }) in the route file's defineRoute
X_ROUTE_MODE_INVALID render mode not allowed on this surface, or not a render mode at all stream on a site/ route; render: 'spa', deleted in 6.0.0 render: 'ssr' — static, isr or ssr in site/; stream or ssr in app/. For spa, the migration is one line — render: 'ssr' — in Upgrading
X_ROUTE_NAVIGATION_INVALID a route's navigation is not 'prefetch', 'document', 'modal' or { modal: true, prefetch: 'intent' }, or its surface has no client navigation navigation set to any other value — an object with any other key or value, { modal: true } alone included (that is 'modal') — or set on a page under a surface app.config.ts's navigation.client does not list — no router runs there, so the key would decide nothing. The second half is refused at boot defineRoute({ ..., navigation: 'prefetch' | 'document' | 'modal' | { modal: true, prefetch: 'intent' } }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key
X_ROUTE_OFFLINE_MISSING the route's offline strategy is missing or contradictory precache on an ssr route offline: 'precache' — or 'runtime', 'network-only' — in defineRoute
X_ROUTE_POST_INVALID a page route's post binding cannot be mounted post: names no registered action, is not a string, or sits on a page that is not render: 'ssr' defineRoute({ ..., post: '' }) on an ssr page, naming an action the app registers — x actions list --json prints them
X_ROUTE_STATUS_INVALID a route answered a status a rendered page cannot carry withStatus(302, data) — a 3xx is a Location and no body, and a loader only ever produces a body redirect(location) from @ultimat3/http, thrown or returned by the handler — a page answers 2xx, 4xx or 5xx from load. Out of 200–599 is X_INVARIANT from the same screen every render mode uses
X_ROUTE_UNNORMALIZED a route was registered without defineRoute registerRoute({ config }) was handed the author's own object, so meta and budget were never normalized and every descriptor reader would read them wrong registerRoute({ file, config: defineRoute({ … }) }) — wrap the declaration
X_STYLES_GLOBAL_MISSING a surface renders documents whose CSS defines no :root custom properties nothing in the app's module graph imports the global layer, so every var(--color-*) and var(--space-*) a component emits resolves to nothing and the browser drops the declaration add apps/web/shared/global.scss containing @use '@ultimat3/ui/global.scss'; and apps/web/shared/global.ts containing import './global.scss'; — x new scaffolds both
X_SURFACE_BOUNDARY a surface imported across the hard boundary site/ reached app/, transitively x fix boundary <file>, or move the shared module out of shared/ui

Clone this wiki locally