Repository navigation
Error Codes testing
github-actions[bot] edited this page Nov 17, 2026
·
3 revisions
Part of Error codes: every code @ultimat3/testing registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix |
|---|---|---|---|
X_CASSETTE_MISSING |
a cassette replayed with no recording on disk | cassette() ran in replay mode and |
ULTIMATE_CASSETTE=record bun test <file> — with cassette(import.meta.dir, , { record: { hosts: [] } })
|
X_CASSETTE_RECORD_REFUSED |
a cassette recording was refused | ULTIMATE_CASSETTE=record ran under CI, or the run requested a host outside record.hosts |
cassette(import.meta.dir, <name>, { record: { hosts: [<host>] } }) — add the host, and record locally with CI unset |
X_CASSETTE_SECRET |
a cassette about to be written holds a secret value | the value of a redacted env key or a declared secret appears in the bytes about to be written (raw, percent-encoded, base64 or base64url); nothing was written |
cassette(import.meta.dir, <name>, { redact: (text) => text.replaceAll(<value of KEY>, '[redacted]') }) — then re-record |
X_CASSETTE_UNUSED |
a cassette entry was never replayed | the code under test no longer makes a request the cassette recorded, so the recording describes a run that does not happen |
ULTIMATE_CASSETTE=record bun test <file> — re-record — or delete the entries meta.unused names from the cassette file |
X_DRILL_FAILED |
a fault drill property did not hold | x drill played a fault against the app and a framework contract the drill states (a coded answer, a bounded request, readiness, recovery, a terminal job, a drained role) was not met; the property and its evidence are printed |
x drill <name> --json — read the failed property and its evidence, then explain the code that evidence names: x errors explain
|
X_DRILL_SERVICE_MISSING |
a fault drill needs a service that is not there | x drill needs a real Postgres for every drill, and a real Redis or NATS for the drill that faults it: the TEST_* URL is unset, or the app declares no redis cache tier or nats transport to fault |
docker compose -f docker/docker-compose.test.yml up -d --wait — then: set -a; . docker/test-services.env; set +a |
X_E2E_A11Y_VIOLATION |
a page fails the accessibility audit | a page in this test has a control, image or heading with no accessible name, no title or lang, or focus inside aria-hidden; the cause lists each element | name it (visible text, aria-label, <label for>, alt; alt="" for a decorative image), or e2eTest(name, body, { a11y: { allow: [{ role, selector, because }] } }) |
X_E2E_APP_FAILED |
the app an e2e run spawned did not come up | the reset, the seed or the boot of the app the e2e step spawned failed. The cause names the step and carries its output. The app runs on a throwaway ULTIMATE_STATE_DIR (its own embedded database, disk and dev lock), so your own .x/ is untouched |
x dev --json: boot the same app by hand and read why it would not start |
X_E2E_EVALUATE_CAPTURED |
a page.evaluate() closure named a binding the page does not have | raised from the page's own ReferenceError, naming the binding, because no static scan can catch it: measured on Bun 1.4.0, const wanted = 3; (() => wanted === 3).toString() is "() => !0" — the transpiler constant-folds a captured primitive away before toString() runs, so a captured value may not exist in the source at all |
pass the value through the page instead of closing over it |
X_E2E_EVALUATE_THREW |
an expression an e2e page ran threw inside the browser | the in-page wrapper catches and answers a value, so the name and message survive the crossing instead of arriving as an opaque evaluation failure | read the reported name and message; the throw happened in the page, not in the test process |
X_E2E_EVALUATE_UNSUPPORTED |
a page.evaluate() closure cannot be sent into the browser | the closure is native or bound, declares a parameter, or its source is not an expression — there is nothing to send. Refused statically, before a round trip | rewrite as a zero-parameter closure over page globals only |
X_E2E_LOCATOR_AMBIGUOUS |
an e2e locator matched more than one element and was asked to click | an assertion handed three matches has an answer; a click does not, so isVisible()/count() answer and click() refuses — the "wrong receiver throws, wrong value returns" rule |
add .first(), or narrow the locator |
X_E2E_LOCATOR_EMPTY |
an e2e locator matched no element | resolved lazily, so this is raised at the question, not at construction — the selector, role or text is quoted back as the call that was written | print what the page actually rendered: await page.evaluate(() => document.body.innerHTML), then narrow or correct the locator call the cause quotes back |
X_E2E_SERVICE_WORKER_ABSENT |
no service worker took control of the page within the budget | bounded in the page rather than by a loop in the harness, so there is exactly one retry mechanism; an unbounded wait is a test that hangs rather than fails | confirm the page registers one: await page.evaluate(() => navigator.serviceWorker?.controller !== undefined) — if it does, pass a longer budget to waitForServiceWorker({ timeoutMs })
|
X_EXERCISE_ACTOR_USER_UNSEATED |
the exercise pass could not seat its actor's x_users row | x exercise writes one x_users row per actor it acts as (an app on @ultimat3/auth reads ctx.actor.id as one), and the insert was refused — a column the app added to x_users with no default, usually | x exercise --json # after a migration under packages/db/migrations/ gives the column the app added to x_users a default, or makes it nullable |
X_EXERCISE_EMPTY_REACH |
an exercised primitive was reached and sent no statement and had no effect | x exercise reached the primitive with its exercise input, and the call sent no SQL statement and recorded no effect — its scale, tenant and crash proofs are vacuous (a sweep of nothing is flat). Usually the input takes an early return: an empty list, a missing row, a no-op branch | edit exercise.ts: give each primitive the warning names an input that reaches its work, e.g. defineExercise({ '<name>': { input: () => ({ … }) } }), or mark it { off: '<why>' }; then x exercise --json |
X_EXERCISE_INPUT_THREW |
an exercise entry's input threw | the input function of a defineExercise() entry threw before the pass could call its primitive — the throw is apps/web/exercise.ts's, never the handler's |
x exercise <name> --json — after the entry's input in apps/web/exercise.ts returns a value (it runs as the seated actor, inside the call's request), or { off: '' }
|
X_EXERCISE_SEED_FAILED |
The scale sweep could not write the sized rows of one entity | a sized-seed write for one entity broke a constraint (usually a unique column the default factory repeats), so every primitive reading that table is unproven |
defineExercise({}, { factories: { posts: defineFactory(<the posts entity>, { defaults: (index) => ({ /* each constrained column, distinct per index */ }) }) } }) — in apps/web/exercise.ts, then: x exercise --json |
X_EXERCISE_SETUP_UNSEALED |
an exercise setup let a host through the seal | defineExercise(…, { setup }) called allowHost(): the pass would send a primitive's call out for real, where every vendor is answered by mockFetch or cassette() |
mockFetch('https://<host>/*', handler) — or cassette(import.meta.dir, '') — in apps/web/exercise.ts's setup, in place of allowHost('')
|
X_JOB_CRASH_DIVERGED |
a job run killed at a step boundary made an effect a different number of times than a clean run | an effect — a row write, a mail, a call out, an enqueue — sits outside every step.run, so the retry after a crash makes it again | step.run('<name>', async () => …) around the printed effect, in the job crashProof named; then: x test job --filter <the test file> |
X_JOB_CRASH_UNBOUNDED |
a crash proof needs more kill points than its bound | the job crossed more distinct step boundaries than crashProof kills at — usually one step per row named by something other than the row id (a slug, an email), so the boundaries of one loop do not read as one point and the proof would grow with the rows | step.run(<name>:${row.id}, async () => …) # name a per-row step by the row's id, in the job crashProof named, so its loop is one kill point; then: x test job --filter
|
X_JOB_SIM_INVARIANT |
a simulateJobs seed broke the invariant the test stated | a race between workers, or a fault — kill, lost answer, lapsed lease, duplicate claim, clock jump — leaves the jobs in a state the app forbids |
x test job --seed <n> --filter <the test file> — replays that one seed and its faults |
X_JOB_SIM_NONDETERMINISTIC |
one simulateJobs seed produced two different traces | a job body reads something the simulation does not own — the wall clock, real I/O, state left by an earlier run — so a seed cannot replay |
x test job --seed <n> --filter <the test file> — the first differing event is printed; read the clock and ids through the frozen seams |
X_QUERY_PLAN_UNAVAILABLE |
the database could not answer a generic plan, so no statement was judged | a server older than Postgres 12 (no plan_cache_mode), or one refusing PREPARE |
DATABASE_URL= x verify --only exercise — the embedded database answers every plan |
X_QUERY_SCALES_WITH_ROWS |
a statement shape runs once per row: its count grows with the rows seeded | a loop over rows issuing one statement each — an N+1 — that no test named |
x exercise <primitive> --json — after preload() of the relation the loop reads, or expectedQueryLoop('', fn) around a deliberate loop
|
X_QUERY_SORT_UNSERVED |
a limited read sorts its rows: no index serves the order | an order by whose columns no index on the filtered table holds, in that order, after the equality columns |
x db gen "index <table> <columns>" — after indexes: [{ on: ['', '', ''] }] in entity(''); or, for a sort no index holds, a rewrite or expectedSeqScan('<why>', fn)
|
X_QUERY_UNINDEXED |
a statement no index can serve: the planner can only scan the table | a where clause on columns no index leads with, or a read with no condition at all, seen in the exercise pass |
x db gen "index <table> <columns>" — after indexes: [{ on: ['', ''] }] in entity(''); or scan: '' in that entity(); or expectedSeqScan('', fn) around a read that compares no column
|
X_SEED_GRAPH_ENTITY_UNKNOWN |
a seed plan names an entity its writer was not given | seedGraph and entitySeedWriter were handed two different entity sets | const graph = seedGraph(entities, …); await insertSeedGraph(graph, entitySeedWriter({ entities, … })) |
X_SEED_GRAPH_UNSATISFIED |
no generated row satisfies a table | the seed graph could not build a row for a table: a non-nullable reference cycle, or a CHECK no generated value meets | defineFactory(<entity>, { defaults }) in the app test setup |
X_STATEMENTS_OVER_BUDGET |
One primitive call sent more statements than its ceiling | a single call of an action, query or job issued more than its statement ceiling (100 by default, or the statements: { max, why } of its defineExercise entry) — usually a read per row that a preload would fold |
x exercise <primitive> --json — after preload() of what the call reads row by row, or { statements: { max: , why: '' } } in its entry of defineExercise() in apps/web/exercise.ts
|
X_SUBJECT_ERASE_INCOMPLETE |
a value of the subject survived subjectErase | subjectProof seeded the subject, ran the erase, and found one of its seeded values in a table outside a declared retain: an untreated table, an anonymize that left a column, or a copy of the value in a table with no key to the subject. The cause prints table and column | x exercise --json after adding the table to tables: in defineSubject — or columns: { <table>: '<column holding the key>' } for a copy with no foreign key |
X_TENANT_LEAK |
another tenant's row reached a call's output or effect | the exercise pass called a primitive as tenant B with A's own input (A's ids bound in, where it takes any), before A's own call or after it, and a canary seeded into A's rows, or an id of A's that B was not handed, came back in its output or an effect (a mail, an outbound body, an enqueued job's input) — by an id B chose, or by a statement no tenant predicate scopes. The finding names the path |
x exercise <name> --json — then read the row behind the named path through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement |
X_TENANT_WRITE_CROSSED |
a call by one tenant changed another tenant's row | the exercise pass called a primitive as tenant B with A's own input (A's ids bound in, where it takes any), and a row seeded for A hashed differently after B's call, or was gone — by an id B chose, or by a statement no tenant predicate scopes. Never on a tenant: 'none' job handed none of A's ids: its run is the same whoever enqueues it. The finding names the table and the row's id |
x exercise <name> --json — then write the named row through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement |
X_TEST_ADAPTER_PORT_UNSWAPPABLE |
swapAdapter() was named a port it cannot swap for one test | the port has no process-global slot a test could borrow and hand back, or the name is no ADAPTER_PORTS row — the cause says what a test does instead | await swapAdapter("jobs", memoryJobDriver()) — name a port SwappablePort lists, or do what the cause says for this one |
X_TEST_APP_NOT_BOOTED |
describeApp handle read before boot | the app() accessor describeApp passes its body was called while the describe block was being registered, before its beforeAll booted the app | test('…', () => { const handle = app(); }) |
X_TEST_DB_UNAVAILABLE |
no Postgres for the test template | nothing listening | run x dev (embedded Postgres), or set TEST_DATABASE_URL
|
X_TEST_EVAL_THRESHOLD |
an evalTest() score fell below its threshold |
a prompt or output regressed against options.threshold
|
improve the prompt under test, or lower the threshold passed to evalTest()
|
X_TEST_EXPECTED_INPUT_INVALID |
an assertion named an input its primitive's schema rejects | toHaveBeenCalledWith or toHaveEnqueued parses the expected input through the primitive's own input schema, and it did not parse — no call could ever have matched it | expect(stubbed).toHaveBeenCalledWith(<input the schema accepts>) — the issues are in the cause |
X_TEST_FACTORY_INVALID |
a factory builds a row its own entity refuses | assertFactoriesValid() built and created every factory, and each trait alone, against its entity: a default or trait yields a column value the entity refuses, or a key it declares no column for | edit the defaults or trait the cause names, in the file that declares its defineFactory(…), then re-run assertFactoriesValid(…) |
X_TEST_FACTORY_NOT_PERSISTED |
create() ran with no persister installed |
nothing was attempted — distinct from an insert that failed |
usePersister({ insert: (table, row) => repoFor(table).insert(row) }) in the test preload — or build() for an in-memory row that needs no database |
X_TEST_FACTORY_TRAIT_UNKNOWN |
a factory was asked for a trait it does not declare | a typo at the call site, or a trait never added — the same symptom, so cause lists every declared trait to tell them apart |
defineFactory(<table>, { traits: { <trait>: { /* columns */ } } }) — declare the trait |
X_TEST_FIXTURE_UNAVAILABLE |
a declared fixture has no driver in this process | destructuring page, budget, signIn or deploy with no browser installed. subscribe left this set in 4.2.0 — the framework builds it |
defineFixtures({ <name>: () => yourDriver() }) in the test preload — cause names what the fixture needs |
X_TEST_FIXTURE_UNKNOWN |
a test requested a fixture nobody registered | a destructured fixture name no defineFixtures call declares |
defineFixtures({ <name>: () => buildIt() }) at test setup — cause lists the registered names |
X_TEST_ISLAND_BUILD_REUSED |
an island builder answered the shipped build with the coverage one | under the gate's coverage run mountIsland asks the builder twice — covered to run, shipped for code — and the builder returned the same bundle both times, so code would be the unminified chunk and every size ceiling would read it | mountIsland({ build: buildIslands, root, file })` — the builder itself (describeIslandState already builds once per file), or key your memo by `options.coverage |
X_TEST_ISLAND_NOT_BUILT |
the island build produced no chunk for the file the test named |
mountIsland was given a file the builder never produced — a path relative to the test instead of to the app root, a typo, or an island outside apps/*/{site,app,shared}/**/*.island.tsx. One symptom, three different edits, so cause lists what the build DID produce; an empty list means the glob found nothing under this root at all |
copy a path the cause lists into file: — it is app-root-relative — or, when nothing was built, x g island <name> --at apps/web/site and point root at the directory holding apps/
|
X_TEST_ISLAND_NO_MOUNT |
an island chunk exports no mount function | the island compiled, shipped and was served, and the hydration runtime's m.mount(el, props) finds nothing — a renamed export, or a file exporting only its component. Not a build failure: this one passes every gate and throws in the browser, so cause names the exports it does have |
paste into the island the cause names, using the component the cause names: import { mountOver } from '@ultimat3/render/client'; import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof Counter>[0]): () => void { return mountOver(el, (root) => render(() => <Counter {...props} />, root)); } — the error builds that line from the chunk's OWN exports, so the component is a name that resolves in the reader's file; a chunk exporting nothing usable gets x g island <name> --at apps/web/site instead |
X_TEST_ISLAND_SELECTOR_UNSUPPORTED |
a selector is outside the island DOM's grammar |
find/all/fire/resize/scroll on a mountIsland handle was given a pseudo-class, a comma, a sibling combinator or an unquoted attribute value. The micro-DOM reads compounds of tag, #id, .class, [attr] and [attr="value"] joined by a space (descendant) or > (child), and nothing else — a selector outside that used to MATCH NOTHING, so the assertion after it failed on the wrong question; cause names the offset the parser stopped at |
host.querySelector('[data-role="scroller"] > ul > li button') — inside the grammar: a tag, #id, .class, [attr], compounded and joined by a space or >; or address the element by a data-* attribute the island sets. A :nth-child or :not() question needs a browser test |
X_TEST_ISLAND_STATES_AMBIGUOUS |
two island state manifests answer to one name | resolution is loose on purpose — Settings, settings and settings.island.tsx are one name — so two islands sharing a basename are ambiguous, and they would also share one shot directory |
git mv <the second island> <a-distinct-basename>.island.tsx — the basename is the shot directory, so the two would share one |
X_TEST_ISLAND_STATES_EMPTY |
an island state manifest declares no states |
defineIslandStates was given states: [] — it parses, it registers and it expands to nothing, so the command that photographs it produces no file and exits 0, which is the one outcome a reader cannot tell from success |
states: [{ id: 'empty', title: 'no rows yet', props: {} }] in the states file the cause names |
X_TEST_ISLAND_STATES_MISSING_FILE |
an island state manifest names an island that is not on disk |
assertIslandFiles(manifests, root) found no file at the declared island. The state list IS the expected screenshot set, so a manifest pointing at a moved file expands to pictures that can never be taken |
island: 'apps/web/app/settings/settings.island.tsx' — the path that exists, relative to the app root, not to the states file |
X_TEST_ISLAND_STATES_NOT_PURE |
an island states file imports the component, a renderer or a sibling module | a *.island.states.ts is PURE DATA: the command that takes the pictures must know the complete expected list BEFORE a browser exists, and the harness page and the guard test read the same file. Refused: solid-js, a .tsx/.jsx specifier, any relative runtime specifier (./settings.island resolves to ./settings.island.tsx under Bun, and ./helpers reaches the component one hop further on — a check reading one file's text can follow neither), and a computed specifier, which nothing can read and so nothing may call pure. Allowed: a bare specifier, a relative .json, and import type / export type, which verbatimModuleSyntax erases — an inline import { type X } is NOT erased and is refused. Static, because a module importing Solid still evaluates fine under Bun |
import type { Props } from '<the specifier the cause names>' if only its types are needed — otherwise delete it and inline what it exports as JSON (props: { … }); a computed specifier must be written as a string literal |
X_TEST_ISLAND_STATES_UNKNOWN |
no island state manifest answers to that name |
findIslandStates(all, name) resolved nothing. A typo and an island whose states were never declared are one symptom and two different edits, so cause lists every valid name |
x shot --island <name> with one of the islands the cause lists — or, when none is listed, declare one beside the island: export const states = defineIslandStates({ island: 'apps/web/app/settings/settings.island.tsx', states: [] })
|
X_TEST_ISLAND_STATE_CLOCK_INVALID |
an island state manifest pins a clock that is not pinnable |
timeZone is not an IANA zone Intl knows, or now carries no explicit offset. A harness that freezes the instant and leaves the ZONE ambient renders every date in the host machine's, so one state photographs differently on two machines |
timeZone: 'UTC' and now: '2026-01-01T00:00:00.000Z' — an IANA zone, and an ISO instant ending in Z or an offset |
X_TEST_ISLAND_STATE_DUPLICATE |
two island states share one id | the second picture overwrites the first at the same path, so the run reports two states and leaves one file, with nothing in the output pointing at the loss |
id: '<id>-2' — rename one of them, or to the state it really is: id: 'over-quota'
|
X_TEST_ISLAND_STATE_ID_INVALID |
an island state id is not slug-shaped | the id becomes the screenshot FILENAME stem, so a space, a slash or a capital is either an unguessable path or a path outside the shot directory |
id: 'over-quota' — the id the cause suggests: lowercase letters, digits and single dashes |
X_TEST_ISLAND_STATE_JSON_INVALID |
an island state carries a value JSON does not | island props ride the data-x-props script tag, which is JSON.stringifyd — so a Date, a function, a Map, a cycle, a non-finite number or an undefined is not approximately right in the picture, it is a prop the component never receives. cause names the exact path |
write the value the cause names as JSON — a string, a number, a boolean, null, an array or a plain object |
X_TEST_ISLAND_STATE_STUB_INVALID |
an island route stub is not <METHOD> <pathname>
|
match is a <METHOD> <pathname> PREFIX; a bare path or a lowercase verb stubs nothing, the component fetches for real, the sealed network refuses it, and the picture shows an error state nobody declared |
{ match: 'GET /api/settings', respond: { kind: 'json', body: {} } } in the states file the cause names |
X_TEST_ISLAND_STATE_UNKNOWN |
an island state manifest declares no state with that id |
mountIslandState(manifest, id) or describeIslandState(manifest, id, …) named a state the manifest does not declare. A renamed state and a typo are one symptom, so cause lists every declared id |
mountIslandState(states, '<id>', { build: buildIslands, root }) with one of the ids the cause lists — or declare the state in the <name>.island.states.ts beside the island: { id: 'idle', title: 'the first paint', props: {} }
|
X_TEST_JOB_EXPECTED |
a matcher expected a job declaration and got something else |
toEmitSteps/recordSteps called on job.run or an unrelated value |
toEmitSteps(myJob) — the job export, not toEmitSteps(myJob.run)
|
X_TEST_LIVE_NODE_EMPTY |
the in-process sync node has no live query to serve | the subscribe fixture built a node and found no query({ live: true }) registered — almost always the app's api module was never imported, so defineApi() never named a query. A registry with nothing in it answers every subscribe with "no live query registered", which is a working socket serving no reads |
import the app's api module in the test preload, then x queries list --json
|
X_TEST_LIVE_NODE_UPGRADE_REFUSED |
the in-process sync node refused the connection | the subscribe fixture's node answered the upgrade with a response instead of taking it — its accept budget, its connection ceiling, or a node that was never started. A different failure from having nothing to serve, which is the row below |
await node.start() before connect(), and keep the request path at /_x/sync
|
X_TEST_LOCATOR_EXPECTED |
a matcher expected a locator and got something else |
toBeVisible handed a page, a selector string, or the result of awaiting the locator — anything with no isVisible(). Thrown rather than returned as a failing result, exactly as X_TEST_SCHEMA_EXPECTED is: the assertion is not false, it is unanswerable, and a pass: false would read as "the element was hidden" |
expect(page.getByRole("heading", { name: "Feed" })).toBeVisible() — the locator itself, unawaited |
X_TEST_MAIL_EXPECTED |
toHaveSentMail was handed something other than the mail fixture | the receiver is the outbox a test owns, and this one has no outbox() reader | unitTest(..., async ({ mail }) => { ...; expect(mail).toHaveSentMail(welcomeMail, { to: address }); }) |
X_TEST_MODULE_MOCK_UNRESTORABLE |
a mocked module could not be put back at the file boundary | a test file called mock.module() on a module whose real source threw or did not resolve when loaded for its snapshot, so the next file on this worker would see the fake | x test unit --isolate, or inject the dependency as a parameter instead of mocking the module |
X_TEST_NETWORK_OFFLINE |
the test network is offline | a request made after network.offline() or network.drop()
|
network.online() before the call — or assert the offline path instead of the request |
X_TEST_NETWORK_RACE |
a request raced unsealNetwork() and lost the patched fetch |
unsealNetwork() called while a request from the same seal was still in flight |
await Promise.allSettled(inFlight) before unsealNetwork() — no request from the same test may still be pending |
X_TEST_NETWORK_SEALED |
a test tried to reach the network | an unmocked external call |
mockFetch('<url>', …), or allowHost('<host>') if it must be real |
X_TEST_NONDETERMINISTIC |
a test read wall-clock time or unseeded randomness |
Date.now() in the code under test |
assertDeterministic('…', () => { installDeterminism(); return body(); }) |
X_TEST_NUMBER_EXPECTED |
a matcher expected a finite number and got something else | toBeWithinBudget answered pass:false for a receiver that is not a number (NaN included), so .not.toBeWithinBudget passed on a Promise or undefined | expect(bytes).toBeWithinBudget(limit) — pass the measured number itself, e.g. (await Bun.file(path).arrayBuffer()).byteLength, never a Promise or a string |
X_TEST_OPENAPI_EXPECTED |
a matcher expected an OpenAPI document and got something else | toMatchOpenApi answered pass:false for a receiver that is not an OpenAPI document, so .not.toMatchOpenApi passed on anything at all | expect(await app.openapi()).toMatchOpenApi(committed) — the receiver is the generated document: an object with operations: [{ operationId, required? }] |
X_TEST_PACE_INVALID |
ULTIMATE_TEST_PACE is not a number at or above 1 | the variable the gate sets on each test run it starts was set by hand to a value that does not parse, or to one below 1 |
env -u ULTIMATE_TEST_PACE bun test <file> — the gate measures the pace and sets it itself; unset is pace 1 |
X_TEST_POLICY_EXPECTED |
a matcher expected a policy and got something else | toDenyPolicy answered pass:false for a receiver that is not a policy, so .not.toDenyPolicy PASSED on undefined or a typo. The receiver is checked synchronously and refused with this code, under .not too | expect(post.policy).toDenyPolicy(ctx) — pass the policy object (@ultimat3/policy's, with run() or evaluate()), never the action or its result |
X_TEST_PROPERTY_FAILED |
a property() run found an input its claim refuses | the code under test is wrong for the shrunk input the cause prints, found from the seed it names — or the property returned a promise, so its assertions would run after every draw had passed |
property(gen, fn, { seed: 42, runs: 7 }) — the seed and runs the cause names replay exactly that failure; fix the code under test, then put runs back |
X_TEST_REGISTRY_LEAK |
a test file left a process-global registry dirty | a declareTags() or registerTier() call with nothing to undo it, in a test body or in the file's own beforeAll. Boot calls are the file's to clean up, and a leaked one silently changes the next file's premise — assertKnownTags short-circuits while nothing is declared, so one leaking file switched tag validation on for the rest of the process and a different package's tests failed. The baseline is sampled at the end of module evaluation, not at the first beforeEach: a preload's beforeEach runs after the file's beforeAll, so sampling there counted a beforeAll leak as part of the baseline and reported nothing. The cause names every offending file and what each left behind, never the file that happened to be running when it surfaced |
the fix names the file and ends in a command that reproduces it — in "<file>" add: import { isolateDeclaredTags } from '@ultimat3/cache'; const restoreTags = isolateDeclaredTags(); afterAll(restoreTags); — then re-run: bun test "<file>" — with const restoreTiers = isolateTiers(); afterAll(restoreTiers); for tiers, from the same import. Never a reset: resetTiers() drops what a neighbour registered, and this guard reports additions only, so the damage lands as a failure in an innocent file with nothing pointing back. Entity and job registries are not covered — declaring at module scope is the idiom there, so a test that assumes an empty one calls isolateEntityRegistry() from @ultimat3/testing/registry-isolation (its own entry point, so the general harness does not load the entity registry) instead |
X_TEST_RUN_JOBS_EXPECTED |
toHaveEnqueued was handed something other than the runJobs fixture | the receiver is the queue a test owns, and this one has no enqueued() reader | unitTest(..., async ({ runJobs }) => { ...; await expect(runJobs).toHaveEnqueued(sendWelcome, { userId }); }) |
X_TEST_SCHEMA_EXPECTED |
a matcher expected a Standard Schema and got something else |
toRejectInput/toAcceptInput called on an action instead of action.input
|
toRejectInput(action.input) — the schema, not the action or the query |
X_TEST_SCOPE_UNINSTALLED |
a test double was made in a process the testing preload did not set up | stub() or swapAdapter() ran with no @ultimat3/testing/preload loaded, so nothing would ever put the double back | add preload = ["@ultimat3/testing/preload"] under [test] in bunfig.toml |
X_TEST_SOAK_HEAP_GROWTH |
a soak() run grew the live heap past its stated bound | something keeps a reference per request — a Map with no bound, a listener never removed, a closure held by a module-level array — so the heap after two full collections grew more than maxGrowthBytes |
await Bun.write('soak-heap.json', JSON.stringify(Bun.generateHeapSnapshot())) — after the soak: the type whose count is about the request count is the leak |
X_TEST_STUB_TARGET_UNSUPPORTED |
stub() was handed something that is not an action, llm(), query or job | the argument is not a primitive action(), query() or job() built — often the action's result or its name | await stub(publishPost) — pass the action, llm(), query or job your module exports |
X_TEST_STUB_UNANSWERED |
a stubbed primitive was called before any answer was scripted | stub(target) replaced the body, and the code under test called it before .returns() or .throws() said what to answer | const stubbed = await stub(publishPost); stubbed.returns(<output>) — or .throws(new YourError(...)) — before the code under test runs |
X_TEST_TEMP_TREE_LEFT |
a temp tree survived its own remove | a process the tree never awaited wrote under it while the remove walked it | tree.track(Bun.spawn(['…'], { cwd: tree.path, env: { ...Bun.env, ...tree.gitEnv } })) |
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