Skip to content

EN Reference Error Codes

Jump to bottom
wanoo edited this page Oct 23, 2026 · 1 revision

Error codes and messages

Français · Type: reference · Audience: author, admin, contributor · Context: engine repository, created project, hosted Studio, Reality Bridge · Status: ready · Applies from: 4.4.0

What an error code or an error message of quest'n'click means: the HTTP statuses of the Studio's API (the local dev server and the hosted Studio Server), the Reality Bridge's codes, the solver's statuses, and the exit codes of the commands that check a game. Search this page for the exact code or the start of the message you got: a message with a part filled at run time is written with … in that place.

How to read this page

  • An HTTP answer of the Studio is JSON, { "error": "<message>" }, sometimes with more fields (errors and diff for a 422, unavailable and reason for a 501, the span and its holder for a 423). Look up its status under Studio API, then its message in the list below the status.
  • An HTTP answer of the Bridge is { "error": "<code>", "message": "<message>" }: look up the status and the code under Reality Bridge.
  • A command's exit code (in a terminal, echo $? right after it; in CI, the step's result): see Solver statuses and Exit codes of the checking commands.
  • The messages are the code's own, in English: an API answers in English whatever the page's language. Most come with a troubleshooting page: 409 on the hosted Studio, 423 on the hosted Studio, the Bridge's 409 and 503.

The sections from "Studio API" to "Exit codes of the checking commands" are generated from the code and from wiki/data/errors.json (npm run wiki -- generate reference.error-codes, in the engine repository): a status the code raises and the register does not describe fails npm run wiki -- check.

The dev server's own answers

The local Studio's API (/__studio/api/*, tools/studio/plugin.ts) also answers, outside the StudioErrors listed below:

Status Message When
404 no such endpoint: <path> no route has that path
405 method <METHOD> not allowed on <path> the path exists, with another method
404 no such screenshot GET screenshots/<name>.png of a capture that is not there
404 no such endpoint: assets<path>, no such file the Assets tab's routes: an unknown route, a file outside art/ and audio/
405 method <METHOD> not allowed on assets<path> an Assets route with another method
413 body too large a request body over the bound (the Assets tab takes up to 96 MiB)
500 the error's message anything else thrown: the dev server writes its stack to its terminal

The Bridge's other answers

Besides its BridgeErrors, the Bridge's server (bridge/src/server.ts) answers:

Status Body When
503 { "error": "busy", "message": "the store is busy: try again in a second" }, with Retry-After: 1 another process held the store's write lock longer than the request could wait; nothing was written, send it again
503 { "status": "unavailable" } GET /readyz or /healthz while the store does not answer
500 { "error": "internal" } an unexpected error, logged as a JSON line {"event":"error", …} on its output
404 { "error": "not found" } no route has that method and path

Studio API (dev server and Studio Server)

Every refusal the Studio raises as a StudioError, by HTTP status. The answer is JSON, { "error": "<message>" } (sometimes with more fields); the messages below are the code's, in English. … stands for a part filled at run time.

400

A malformed request: a field missing or of the wrong type, an id that is not one, a body that is not a JSON object, a header of the Studio Server that does not have its form. Nothing was written. Fix the request as the message says and send it again.

Messages:

401

Not signed in, or the credentials are not valid: a hosted Studio's session is missing or expired (the answer may carry login: "/auth/login"), the remote MCP or the metrics came without their token. Sign in again (quest-n-click-studio-server login --server <url> for the CLI and the MCP).

Messages:

403

Signed in, and not allowed: not a member of this project, a role too low for the action (a reviewer writes nothing), a request from another origin, a game page opened outside a browser session, a comment that is not yours, a job someone else started. Ask an owner for the role.

Messages:

404

What the request names is not there: a room, a note, a line, a revision, a build, a job, a file, a storyboard; or a feature this Studio does not have (published builds, comments, the health of revisions are a hosted Studio's; preparing assets, cutting a sheet or upgrading the engine needs its processing worker; Git needs git in the configuration).

Messages:

409

A conflict, nothing overwritten: a file changed since the revision you read (the hosted Studio's stale base), a file changed while the edit was being prepared or checked (try again), an undo whose file changed since, an id that already exists, cells of a sheet that already exist, a job already ended, a build from another history of the game, a Git branch that moved, undo on a shared Studio.

Messages:

413

Too big: a request body over the route's bound (body too large), an upload over the hosted Studio's size, an import of more files or bytes than the Studio takes. Send less, or split it.

Messages:

415

The wrong kind of content: a write that is not sent as JSON, a sound on a hosted Studio that is not an .ogg, .mp3 or .wav file, or whose bytes say it is something else.

Messages:

422

Understood and refused: the edit would add validation errors (the answer lists them, with the diff; nothing is written since 4.2.1), a Git commit that holds no game, or a link or a submodule, prepared assets that would lose files the game had, a cut, a migration or an engine upgrade the processing worker refused.

Messages:

423

A span (a room, a language, the game…) is held by another member of a hosted Studio, or your own lease on it ended: the answer names the span and its holder; your draft is kept.

Messages:

429

Too much at once, try again later: a build or an asset preparation is already running, the engine's upgrade is running, too many jobs wait, too many open comments.

Messages:

500

The game or the Studio itself failed: the game does not load (a syntax error, a former web-scumm/… import), a JSON file of the game is invalid, an edit would break the file it writes (refused, nothing written), a write on a shared Studio without its author. The dev server writes the stack to its terminal.

Messages:

501

Not available here: a screenshot or the captures of a diff without Playwright or its Chromium, or on a hosted Studio (the answer carries unavailable: true and reason); a Reality policy solved on a hosted Studio (local only).

Messages:

502

A service behind the Studio Server failed: a git command or a push to the game's repository.

Messages:

503

Not now, nothing lost: another process is writing this game, the edit cannot be judged now (the validation could not run), or a hosted Studio's identity provider cannot be reached (the session is suspended). Try again.

Messages:

504

The processing worker of a hosted Studio did not answer in time (a preparation, a cut, a diagnostic): try again, or do it on a local Studio.

Messages:

Reality Bridge

Every refusal the Bridge raises as a BridgeError, by HTTP status and code. The answer is JSON, { "error": "<code>", "message": "<message>" }.

400 shape

The request is not what the route reads: not JSON, a field missing or malformed, a through the Bridge never sent, a revocation id that is not hex, a webhook delivery without its id.

Messages:

401 admin

An operator route (/v1/admin/…, as quest-n-click-bridge revoke calls it) without the operator's token (admin-token in the Bridge's folder).

Messages:

401 capability

The player's link to the Bridge (its capability) is unknown, revoked, expired or too old: the player pairs again.

Messages:

401 revoked

The connector's token was revoked while its signal was being proposed: grant a new one (quest-n-click-bridge grant).

Messages:

401 signature

A webhook delivery whose HMAC signature does not match the webhook's secret.

Messages:

401 token

A connector's token that cannot be read, or that was revoked, on a pairing confirmation or a signal.

Messages:

403 denied

The connector's token is valid and does not allow this: it may not pair (granted without --pair), or its Biscuit does not allow that signal, source or player.

Messages:

404 game

A pairing asked for a game this Bridge does not serve (its gameId is another).

Messages:

404 hook

No webhook of that name in the Bridge's configuration.

Messages:

404 pairing

The pairing code is unknown or expired: the player starts a new pairing.

Messages:

404 player

The player is unknown to this Bridge, or was revoked (quest-n-click-bridge revoke --player=…, or the player unlinked).

Messages:

404 tenant

A Bridge serving several tenants found none for this request.

Messages:

409 pairing

The pairing code was already confirmed, by this connector or another one: the player is paired, nothing to redo.

Messages:

410 pairing

The pairing was already claimed: the player's capability was handed out once and never again; pair again from the game.

Messages:

413 size

The request body is over the Bridge's bound.

Messages:

422 event

The webhook does not map that event to a signal (its configuration lists the events it knows).

Messages:

422 signal

The signal is not in the game's Reality manifest.

Messages:

422 source

The signal is declared for another source than the connector that sends it.

Messages:

429 pairings

Too many pairing codes wait for a confirmation: try again in a minute.

Messages:

429 pending

The player has too many signals waiting to be delivered.

Messages:

429 quota

Too many signals this minute for the player (the Bridge's per-minute quota).

Messages:

429 rate

Too many requests from this address: the answer carries Retry-After: 60.

Messages:

429 streams

Too many open event streams: for this player, or for this instance of the Bridge.

Messages:

Solver statuses

The one status of a solver run or of a proof by chapters (src/engine/tools/status.ts): the command line, its --json, the Studio's Check tab and the MCP solve tool all read it.

Status Exit code Means
solved 0 The ending (or the goal) is reached: on one path for a witness search, from every reachable state with --prove.
softlocks 1 Some reachable states can no longer reach the ending: the output lists them with the path to each.
unsolved 1 The ending is not reached from any state explored.
truncated 2 The search stopped on its budget (states --max, time --time, memory --mem): nothing is proved; raise the budget or resume from the checkpoint.
broken 1 An invariant of the game became true on a reachable state.
error 1 The engine raised errors while exploring.
checkpoint_mismatch 1 A proof by chapters (--prove --chapters): every chapter is proved, but a hand-written checkpoint is none of its chapter's reachable boundary states.

Exit codes of the checking commands

What a script or a CI job reads after the command.

npm run validate

tools/validate.ts.

Code Means
0 No error (warnings may be printed); --report always exits 0.
1 At least one error, listed after ✖.

npm run solve

tools/solve.ts.

Code Means
0 solved; also --prove --chapters on a game that declares no chapter.
1 Any other status but truncated (softlocks, unsolved, broken, error, checkpoint_mismatch); with --audit-abstractions, the two searches diverged.
2 truncated: nothing proved (with --audit-abstractions, the explicit search was truncated); or a refused --goal (only --goal=100%, and only on a game with an objective that is not optional).

npm run solve:reality

tools/solve-reality.ts.

Code Means
0 Every world proved (closed, each scenario and replay, adversarial), or a game without reality.
1 A world fails; a truncated search counts as a failure.

npm run lint

tools/lint.ts.

Code Means
0 No finding of severity error, and the solver's search was not truncated.
1 At least one finding of severity error.

npm run doctor

tools/doctor.ts.

Code Means
0 Every required prerequisite is there (optional ones may be missing).
1 A required prerequisite is missing; with --release, every prerequisite of npm run release-check is required.

npm run speedrun:verify

tools/speedrun/verify.ts.

Code Means
0 The verdict is valid or valid-unranked.
1 Any other verdict, inconclusive included: never valid.
2 No .wsrun file named: the usage line is printed.

npm run e2e:canonical

scripts/e2e-canonical.mjs.

Code Means
0 Every browser writes every value as Node does (or a browser skipped with --allow-skip, said on the output).
1 A browser writes a value differently.
3 A browser Playwright cannot launch here, without --allow-skip.

npm run e2e:remix

scripts/e2e-remix.mjs.

Code Means
0 Every runtime makes the same worlds (or a browser skipped with --allow-skip, said).
1 A difference, the seed named.
3 A browser Playwright cannot launch, without --allow-skip.

npm run e2e:speedrun

scripts/e2e-speedrun.mjs.

Code Means
0 Determinism proved in every browser run (or --bundle-only, or a browser skipped with --allow-skip).
1 A check failed.
3 A browser Playwright cannot launch, without --allow-skip.

npm run e2e:pwa

scripts/e2e-pwa.mjs.

Code Means
0 Proved; or skipped with --allow-skip (an explicit "skipped" line, never a proof).
1 Failed.
3 Skipped: the browser cannot navigate offline under automation (WebKit), without --allow-skip.

npm run e2e:remix-speedrun

scripts/e2e-remix-speedrun.ts.

Code Means
0 Every world policy recorded the same run in every runtime, verified (or a browser skipped with --allow-skip).
1 A check failed.
3 A browser Playwright cannot launch, without --allow-skip.

npm run lint: exit code 2

Besides 0 and 1 above, npm run lint exits 2 when it found no error but the solver's search it runs first was truncated: "never run" and "never reached" are then information, not verdicts. Raise --max, or prove by chapters (tools/lint.ts).

Limit · register-scope The register lists what the code raises with a structure: new StudioError(<message>, <status>) in studio-server/src/ and tools/studio/, new BridgeError(<status>, '<code>', <message>) in bridge/src/, the solver's statuses and the exit codes named in the data. It does not list the answers a route sends directly (the Studio Server's 429 too many requests and 429 too many refused attempts, with Retry-After: 60; the Bridge's speedrun and daily routes, /v1/runs and /v1/daily, with their own error bodies), a refusal whose status is computed (the Bridge's signal check answers 401 or 403 with the Biscuit check's own code), nor the text of a message built at run time (counted under its status). The speedrun verifier's verdicts and codes belong to the speedrun pages.

Related identifiers

Edit the source of this page · Report an error

Generated publication · publication générée — current documentation · documentation courante: quest'n'click 4.4.0 r1, documentation revision · révision de la documentation 8dc717c69acb62c4742b69c54a7e7dfb620f75d8. Earlier versions and permalinks · versions précédentes et liens permanents: https://wanoo.github.io/quest-n-click/docs/ An edit made in this wiki is overwritten at the next publication · une modification faite dans ce wiki est écrasée à la publication suivante. Edit the source · Modifier la source · Report an error · Signaler une erreur

Home

Index (6)
Start (6)
Play (9)
Install (17)
Create a game (55)
Engine (4)
Local Studio (24)
Team Studio (21)
Clever Cloud (23)
Reality Bridge and connectors (16)
Contribute (25)
Reference (7)

Clone this wiki locally