Troubleshooting

Each entry starts with what you see in the app.

Agents

Desktop “No coding agent found” in the composer. No supported coding CLI is installed or signed in, so the chat can’t send; the Send button’s tooltip says No coding agent detected. Open Settings → Agent (the composer’s Settings link goes there) and use Install and sign in on Claude Code, Codex or OpenCode. The CLI shows up in the model picker straight away, with no restart. See Settings → Agent.

Hosted “No models are set up on this server yet”. The server has no model provider configured. Whoever runs it adds one; see Model providers.

Previews

A frame never shows the app. It stays on Starting dev server, or ends on Dev server not responding or Setup failed. On a failure, click Open logs on the frame: the chat’s Dev server terminal shows the dev server’s and portless’s output. The usual cause is a run script that doesn’t serve on the port Screenplay assigned, covered next. Fix what the logs show, then click Retry. You can also ask the chat’s agent to debug the preview, since it reads the same output.

Desktop “The dev server didn’t start on the port Screenplay gave it”. This is DevServerPortIgnoredError: the dev server is running but never listened on its assigned port, usually because the run script ignores $PORT.

Edit the repository in Canvas settings and add the port to its Run script, for example vite --port $PORT --strictPort.
Use … → Restart → Restart dev server on the chat.

See When the preview never loads.

A Turborepo dev server ignores the port. Turborepo 2’s strict env mode strips variables a task doesn’t declare, so $PORT is empty inside the task, and a package script that hardcodes --port 3001 wins over the variable anyway. Pass the port as a flag after --, which works for Next.js and Vite because the last --port wins:


turbo run dev --filter=web -- --port $PORT

Alternatively, add "passThroughEnv": ["PORT"] to the dev task in turbo.json. See Monorepos.

Chats

Desktop “The branch … is already open in another chat on this computer”. On desktop each chat’s code is a git worktree of one shared clone, and git checks out each branch only once. Close the chat that has the branch open, or open a different branch. See One branch, one chat.

Desktop “The branch … is checked out in your local clone”. The same limit, against your own checkout: the agent would be editing your clone directly. Switch your clone to another branch, then open the chat again.

Desktop “Not a git repository”. The folder you added isn’t a git repository. Add a local clone or a GitHub repository instead; see Adding a repository.