Repository navigation
Error Codes render
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
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
|
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference