Common failure modes and their fixes, roughly by how often they hit. Your first stop is always get_bridge_status — it reports the IPC dir, heartbeat age, version, and a real round-trip result.
Most common cause: an IPC directory mismatch. The MCP server (Node) resolves its temp dir from TEMP; the s&box addon (C#) resolves from TMP. On some Windows setups those differ, so the server writes requests into a folder the addon never reads.
Find the dir the addon uses (Editor → Claude Bridge → Status, or the ipcDir in status.json), then point the server at it with SBOX_BRIDGE_IPC_DIR. The addon does not honor an env override (sandbox safety), so always realign from the server side.
s&box isn't running, the project failed to load, or the addon failed to compile. Note: you do notneed the Claude Bridge dock open — since v1.3 the bridge runs on a static frame handler that processes requests with the dock closed. If the heartbeat is stale, check that s&box is open and the addon compiled (see the next item).
Just read the error — get_compile_errors and read_log run server-side, so they work even when the editor is in a broken state. Fix the file the error names, trigger_hotload, and re-check. If game code fails to compile, the editor-side bridge fails too (Broken Reference: package.local.X) — the tool.frame message is usually a wrapper, not the real cause.
take_screenshotalways renders from the scene's Main Camera — one fixed angle. Use screenshot_from instead: it moves the camera to frame a target object or point, captures, and restores it. (frame_cameraonly moves the editor viewport, which the screenshot doesn't use.)
The bridge deliberately refuses scene-mutating commands while the game is playing — mutating the scene during play can corrupt .scene files on save. Call stop_play, make your edits, then start_play again. Read-only tools, screenshots, and runtime-property tools are safe during play.
An older installer copied the addon into s&box's global addons/ folder, which is built-in only and silently refuses to compile custom C#. The addon must live in your project's Libraries/claudebridge/ folder — reinstall from the Asset Library (or run the installer with the remove-stale flag).
Keep the addon and the MCP server on the same major.minor. “Unknown command” round-tripping to the editor means the server is newer than the addon — reinstall the addon. A handlerCountwell below the documented number means the addon didn't fully compile — check get_compile_errors. If you upgrade one half, upgrade both.
The MCP server process started and immediately exited — usually a missing build (dist/index.js), a wrong/relative path, or Node older than 18. If you use the plugin, run /reload-plugins or restart Claude Code.
The experimental runtime ParticleEffect tools (spawn_particle, add_trail, add_beam) don't render through the bridge. Use spawn_vpcf — it plays a compiled .vpcf, the supported visible particle path. Author the effect in s&box's particle editor, then Claude can spawn it.
The project has both a local-dev Libraries/claudebridge/and an asset-library-installed copy claiming the same compiler name. Keep one — either set the local copy's Org to local, or remove the asset-library copy.
get_bridge_status result and get_compile_errors, then open an issue on GitHub or email sboxskins@gmail.com. See also the FAQ.