Skip to content
quest'n'click

StudioTroubleshootingFor authorsApplies from 4.2.1

Studio troubleshooting

Cette page en françaisThis page on the GitHub wiki

The local Studio refuses something, or a tool in it says it is unavailable. Find the exact message below: each one has its cause and its fix. Nothing in this page concerns the hosted Studio, whose 409 and 423 have their own pages (see "Neighbouring cases").

Symptom

The messages, as the Studio, its server or the MCP server print them:

Message or codeWhereSection
✖ games/<id>/index.ts not found (GAME=<id>)Terminal, at npm run studioStart
400 invalid HostBrowser or scriptAccess
403 the Studio answers its own names only (localhost, 127.0.0.1, [::1], or the address dev:lan serves)Browser, phoneAccess
403 cross-origin Studio request refusedBrowser, scriptAccess
403 Studio writes require a same-origin Origin headerScript (curl, an agent's HTTP call)Access
401 Studio token requiredPhone, browser in LAN modeAccess
503 LAN Studio token is not configuredLAN mode started by handAccess
422 refused: the edit adds N validation error(s): …A toast in the StudioEdits
422 refused: the game would no longer load after the edit (…); nothing was writtenA toastEdits
500 refused: the edit would break <file> (…)A toastEdits
409 cannot undo "<what>": <file> changed sinceUndo in the headerEdits
409 with conflictsAssets tab uploadEdits
501 unavailable … Playwright is not installed (npm i -D playwright && npx playwright install chromium)Check tab: Screenshot, capturesChecks
The voice table needs the dev server (npm run studio). / The scenario map needs the dev server or a hosted Studio.Demo StudioChecks
custom provider URLs are disabled (set WEB_SCUMM_ALLOW_CUSTOM_PROVIDER=1 to opt in)AssistantAssistant
<url> did not answer within 60 s, the provider's answer exceeds 8 MB, … answered with a redirect …AssistantAssistant
The MCP client cannot parse the server's output; Claude Desktop cannot start npmAI clientMCP

Possible causes

Start

  • GAME (or the game last chosen with npm run game, or config.game) names a folder without index.ts: a typo, or a game not created yet.

Access (400, 401, 403, 503)

The Studio's routes answer only their own machine, same-origin requests, and in LAN mode the session's token (Local and LAN security).

  • 403 own names: the page was opened by a name that is not localhost, 127.0.0.1 or [::1] (a custom host name, the machine's address without studio:lan), or a page tried DNS rebinding.
  • 403 cross-origin: the request came from another origin (another port, another site, a page opened from a file).
  • 403 same-origin Origin header: a write sent without an Origin header (curl, a script).
  • 401 token: LAN mode, and the request carries no token, or the token of an earlier session (a new one is drawn at each start).
  • 503 token not configured: WEB_SCUMM_LAN=1 was set by hand without WEB_SCUMM_STUDIO_TOKEN.
  • 400 invalid Host: a Host header missing or holding spaces, /, @ or \.

Edits (409, 422, 500)

  • 422: the guard judged the game as it would be after the edit, and the edit adds validation errors or stops the game from loading. Nothing was written (Preview, apply, undo).
  • 500 would break: the change would make the file's TypeScript invalid.
  • 409 undo: the file was written again since that operation (by an AI, an editor, git, or another write of the Studio). Another 409, without undo: a file another process rewrote while the edit was being prepared.
  • 409 conflicts: an uploaded sheet would recut cells that exist, and they were not named (Assets and cutting).

Checks and tools (501, "needs the dev server")

  • 501: Playwright or its Chromium is missing on this machine (Screenshot, before/after captures); or the Studio is a hosted one, which has no captures.
  • "needs the dev server": the demo Studio has no server: no voice table, no scenario map, no semantic diff, no structured writes, no screenshots (Demo mode).

Assistant

  • Custom provider disabled: the base URL is not a preset (OpenAI, Anthropic, Mistral) nor Ollama on this machine.
  • HTTPS / private host: with the opt-in, the URL is http:// or a local or private address.
  • 60 s, 8 MB, redirect: the provider was too slow, answered too much, or redirected (The Assistant).
  • CORS in the demo: the provider refuses calls from a web page (OpenAI does for some keys).
  • "Stopped after 12 tool rounds": the request needed more rounds than one turn allows.

MCP

  • The client cannot parse the output: the config runs npm run mcp without -s, and npm's banner reaches stdout.
  • Claude Desktop cannot start npm: it does not have your shell's PATH.
  • The wrong game: GAME unset, so the server took the game last chosen or config.game.

Diagnosis

  • The browser's network panel shows the status and the body (the message above) of the refused request.
  • The terminal running npm run studio shows the dev server's errors; the MCP server writes its own on stderr, with [quest-n-click mcp] in front.
  • In LAN mode, compare the URL you opened with the one the command printed: host, port and token=.
  • For a 422, the toast lists the first errors; the Check tab gives them all.

Fix

  1. Start. Point GAME at a game that exists:

    # in the engine repository
GAME=demo npm run studio
  1. Access. Open the Studio at http://localhost:5173/__studio/ on the machine itself. From a phone, start npm run studio:lan and open the URL it prints, token included; after a restart, open the new URL. A script sends Origin: http://localhost:5173 (and in LAN mode x-web-scumm-token: <token>). Never set WEB_SCUMM_LAN=1 by hand: use the LAN scripts.
  1. Edits. For a 422, read the errors and change the value; for an undo refused, compare with git diff and take the file back with git; for a 409 conflicts, tick recut on the cells to replace.

  1. Playwright. Install it where the Studio runs:

    # in the engine repository or the created project
npm i -D playwright && npx playwright install chromium

  1. Assistant. Use a preset, or restart with the opt-in for an HTTPS public endpoint:

    # in the engine repository or the created project
WEB_SCUMM_ALLOW_CUSTOM_PROVIDER=1 npm run studio

    For a local model, use the Ollama preset; in the demo Studio, Ollama with OLLAMA_ORIGINS=<the page's origin>, or the local Studio. After "Stopped after 12 tool rounds", ask again to continue.

  1. MCP. Write npm run -s mcp in the client's configuration; for Claude Desktop, npm's absolute path (which npm) in command; add "env": { "GAME": "<id>" } (Local MCP: setting up each client).

How to check it is fixed

The Studio opens on the Rooms tab and a text edit shows its toast; the Check tab's badge is green; the Assistant answers; the MCP client lists the quest-n-click tools and list_rooms answers.

Neighbouring cases