#Troubleshooting

Most issues fall into a handful of buckets. Find yours below. Still stuck? Get help.

#A chatspace is stuck "preparing"

Setup has a few steps (claim machine → clone repo → start agent → sign in). If it's taking a while:

  • It may be waiting on sign-in. If this is your first time with the agent, the chatspace is waiting for you to complete the login flow. Look for a login link or device code in the app.
  • Give it a moment, then retry. Tap to reopen the chatspace; transient hiccups usually clear.
  • Recreate it. If it stays stuck, delete it and create a new one with the same settings — a fresh machine almost always comes up clean.

#The agent isn't responding

You've opened the chatspace and sent a message, but the agent just sits there — it looks online (idle, or even "working"), yet no reply ever comes. You might also see a connection error in the Claude or ChatGPT app.

This is almost always upstream throttling by the AI provider — Anthropic for Claude sessions — and not a problem with your machine, your account, or Chatspaces itself. The provider's API starts refusing that machine's connection, and once it does, it doesn't tend to recover on its own. It's specific to that one machine: your other chatspaces keep working normally.

  • Recreate the chatspace. This is the reliable fix: start a new chatspace with the same prompt. It comes up on a fresh machine that the provider treats as a clean slate. Resuming or stopping/starting the same chatspace reuses the same machine, so it usually won't clear this.
  • Your work is safe. Recreating doesn't touch your repo or branch — you only lose the chat context of that one stuck session.
  • Don't launch a burst at once. Starting several chatspaces in the same few seconds makes the provider more likely to throttle them. Give each one a moment before starting the next.

#I keep getting asked to sign in

  • Your saved agent login likely expired or was revoked (you signed out of Claude/ChatGPT elsewhere, rotated credentials, or your plan lapsed). Just sign in again — Chatspaces will save the fresh login if you allow it.
  • If you opted out of saving your login, signing in each session is expected. Turn saving on in settings if you'd rather not.
  • Confirm your subscription is active — Claude Pro/Max for Claude, a ChatGPT account for Codex.

For live preview links:

  • Is your app actually running? The link only works while the server it points to is up. Ask the agent to (re)start it.
  • Is the route set? There must be a rule pointing the path at the right port (e.g. / 3000). The simplest fix is to ask the agent: "expose the dev server on a public link."
  • Right port? Make sure the route's port matches the port your app is listening on. Don't use 8080 — it's reserved.
  • Is the chatspace running? A stopped chatspace serves nothing. Resume it.

#It stopped on its own

That's idle stop — chatspaces auto-stop after about 10 minutes of inactivity to save your usage. Nothing is lost; tap Resume to continue.

If it keeps stopping while you're still working:

  • You may be doing work the agent can't "see" (long terminal sessions, hitting the preview URL without talking to the agent). Turn idle stop off for that chatspace, or set a longer timeout.
  • To reset the timer, just interact with the agent again.

#I hit a usage or chatspace limit

  • "Usage exceeded" when resuming/creating: you've used your weekly budget. A running chatspace keeps running; new starts are blocked until your weekly reset — or you can upgrade and continue immediately.
  • "Too many running": you're at your plan's running at once limit. Stop one to start another.
  • "Too many chatspaces": you're at your total limit. Delete one you're done with, or upgrade.

#I can't delete a chatspace

If it has uncommitted changes or unpushed commits, deletion is gated so you don't lose work. Either:

  • Ask the agent to commit and push first, then delete; or
  • Confirm in the delete dialog that you want to discard the work.

#My Codex session looks offline in ChatGPT

The connection between your chatspace and ChatGPT occasionally drops. Stop and resume the chatspace to reconnect. If a stale device lingers in ChatGPT, remove it under Settings → Connections in the ChatGPT app.

#Changes I expected aren't on GitHub

The agent only pushes when it commits. Ask it to commit and push (or open a PR). If pushing fails, check that the GitHub App is installed for that repo's owner, or that your GITHUB_TOKEN (if you're using one) is valid and has the right scope.

If none of this helps, get in touch — include the repo, what you tried, and any error message you saw.

← Previous Provider credentials Next → Getting help