| What you see | Fix |
|---|---|
| The OpenScaffold tools don’t show up | Tools load when a session starts. Restart the agent (Claude Code: /exit, then claude --continue), or start a new task in Codex or a new chat in Cursor |
401 or “Not signed in to OpenScaffold” | CLI login: run npx @openscaffold/cli@latest login again. Plugin, Cursor, Codex, VS Code: sign in again from the agent’s MCP settings (Codex: codex mcp login openscaffold) |
status says “login revoked” | It was disconnected in Settings → Connected agents. Run login again |
status says the server isn’t answering | The login points at a server that’s down, often a local dev server. Start it, or run OPENSCAFFOLD_URL=https://app.openscaffold.ai npx @openscaffold/cli@latest login |
| Your customer isn’t listed | The agent is in another workspace. Disconnect it in Settings → Connected agents and sign in again, picking the right one. CLI: run login again and approve in the right workspace |
| ”No deployment loaded” | The session couldn’t tell which customer. Say “load <customer>”, or “set up <customer> from these files” for a new one |
| ”No active deployment dep_…” | The id is wrong or the deployment is archived. Ask the agent to call list_deployments and pick one |
| ”Documents are still being read” | Wait a minute; the plan starts on its own once they are |
| ”No findings yet” | The files had nothing the plan can use, or were empty. Add call transcripts, tickets or emails |
| The plan never appears | Open the deployment’s Overview in the app: a failed build shows its error and Retry. No error and no build running: press Build the plan |
| ”needs Node 22 or newer” | Install Node 22+ from nodejs.org or with nvm install 22 |
| No browser opens (SSH, headless Linux, WSL, containers) | The CLI prints the link. Open it on any device where you can sign in and click Approve. Set OPENSCAFFOLD_NO_BROWSER=1 to never try |
| The login link expired | Links last 10 minutes and work once. Run login again |
| Claude Code isn’t on PATH | login prints the exact claude mcp add command to run once it is |
| Every tool and command shows up twice | Both the plugin and an older CLI login added the server. Run npx @openscaffold/cli@latest login again: with the plugin installed it keeps only the plugin’s |
| Sign-in loops or says the app can’t connect | Start the sign-in from the agent itself, not an old browser tab. Only agents running on your machine can connect |
| The agent answers without using OpenScaffold | Name it: “Use OpenScaffold to…”, or load the customer first: “load <customer>” |
Reference
Troubleshooting
What you might see while connecting an agent or setting up a customer, and the fix.