Skip to content
quest'n'click

ReferenceReferenceFor authors, admins, contributorsApplies from 4.4.0

Error codes and messages

Cette page en françaisThis page on the GitHub wiki

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:

StatusMessageWhen
404no such endpoint: <path>no route has that path
405method <METHOD> not allowed on <path>the path exists, with another method
404no such screenshotGET screenshots/<name>.png of a capture that is not there
404no such endpoint: assets<path>, no such filethe Assets tab's routes: an unknown route, a file outside art/ and audio/
405method <METHOD> not allowed on assets<path>an Assets route with another method
413body too largea request body over the bound (the Assets tab takes up to 96 MiB)
500the error's messageanything 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:

StatusBodyWhen
503{ "error": "busy", "message": "the store is busy: try again in a second" }, with Retry-After: 1another 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

Generated from the engine's own data

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.

StatusExit codeMeans
solved0The ending (or the goal) is reached: on one path for a witness search, from every reachable state with --prove.
softlocks1Some reachable states can no longer reach the ending: the output lists them with the path to each.
unsolved1The ending is not reached from any state explored.
truncated2The search stopped on its budget (states --max, time --time, memory --mem): nothing is proved; raise the budget or resume from the checkpoint.
broken1An invariant of the game became true on a reachable state.
error1The engine raised errors while exploring.
checkpoint_mismatch1A 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.

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

npm run solve

tools/solve.ts.

CodeMeans
0solved; also --prove --chapters on a game that declares no chapter.
1Any other status but truncated (softlocks, unsolved, broken, error, checkpoint_mismatch); with --audit-abstractions, the two searches diverged.
2truncated: 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.

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

npm run lint

tools/lint.ts.

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

npm run doctor

tools/doctor.ts.

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

npm run speedrun:verify

tools/speedrun/verify.ts.

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

npm run e2e:canonical

scripts/e2e-canonical.mjs.

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

npm run e2e:remix

scripts/e2e-remix.mjs.

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

npm run e2e:speedrun

scripts/e2e-speedrun.mjs.

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

npm run e2e:pwa

scripts/e2e-pwa.mjs.

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

npm run e2e:remix-speedrun

scripts/e2e-remix-speedrun.ts.

CodeMeans
0Every world policy recorded the same run in every runtime, verified (or a browser skipped with --allow-skip).
1A check failed.
3A 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).