AgentGridAgentGrid Docs
Troubleshooting

Common Errors

A reference of common errors you might see in AgentGrid and how to fix them.

This page collects errors that surface in a pane or a dialog, what causes them, and how to recover.

"No conversation found with session ID: <id>"

You'll see this inside a pane, often paired with auto-resume stopped after 3 attempts — click Resume to retry.

Cause. AgentGrid is trying to resume a Claude Code session — for example after you restart the app — but the underlying Claude Code session transcript no longer exists on disk. Claude Code deletes session transcripts after 30 days by default. Once a transcript is gone, AgentGrid can't resume that pane; the conversation history is no longer available to replay.

Fix. Extend how long Claude Code keeps sessions. In your Claude Code settings file at ~/.claude/settings.json, set cleanupPeriodDays to a larger retention window (in days). For example:

{
  "cleanupPeriodDays": 365
}

Then restart AgentGrid. New sessions will be retained for the extended period.

Sessions that were already deleted before you changed this setting cannot be recovered. cleanupPeriodDays is a global Claude Code setting and affects every Claude Code session on your machine, not just the ones started from AgentGrid.

Keep working in the meantime. If a single pane shows this error, you can start a fresh session in that space and keep going — only that pane's prior history is lost. Other panes and spaces are unaffected.

No traces in Langfuse after enabling Observability

Cause. Export is off by default, uses Agent Grid’s fixed managed endpoint, and only applies to new agent harness sessions — not plain shells and not sessions started before you saved settings.

Fix. Confirm Settings → Observability is enabled (if the tab is missing, turn on Show Observability in Settings → Advanced), keys and OTLP endpoint match your Langfuse project (http://127.0.0.1:23841/api/public/otel for managed local Langfuse), Docker is running if you use local Langfuse, then spawn a new Claude session and check Langfuse again. Step-by-step: Observability with Langfuse.

Local Langfuse won't start. If you see Langfuse can't start because its ports are in use, another process or Docker container already holds the managed web port 23841 or MinIO API port 23842. The message names known Docker owners and how to stop them. Free both ports, then try again; Agent Grid never falls back to another port.

"Usage limit reached" or "Weekly limit reached"

You'll see a turn stop with a line such as Claude usage limit reached or Codex usage limit reached, often with when it resets. The usage menu in the title bar shows Weekly limit reached.

Cause. The account behind that pane used up its plan's allowance for the current window. AgentGrid doesn't set these limits; your provider does.

Fix. Pick one of the other models or accounts the notice offers, or turn on Auto-switch so AgentGrid tries your other accounts on that harness by itself, and waits for the one that resets first when they're all at their limit. You can also choose Wait · resumes … to continue when the limit resets; tick Always do this to make that the default.

"Approaching weekly limit"

You'll see a banner such as Approaching weekly limit · resets … above a Claude conversation, and Weekly limit nearly reached in the usage menu.

Cause. The account is close to its limit. Nothing has stopped yet.

Fix. Nothing is required. Dismiss the banner; it stays hidden until the limit resets. If the work matters, move it to another account or model before it runs out.

"Selected model is at capacity"

You'll see Selected model is at capacity. Please try a different model. end a Codex turn, even when your usage menu shows plenty left, say 49%.

Cause. OpenAI's servers are overloaded for that model right now. It has nothing to do with your plan's usage percentage.

Fix. Pick another model in the model picker and send "continue". The pane keeps its conversation, so the work picks up where it stopped. With Auto-switch on (it needs AgentGrid Pro or an active Pro trial), AgentGrid does this for you: it skips only that model and moves to your next starred model, which can be on the same harness.

"gpt-6.2-sol isn't available to this Codex login"

You'll see this end a Codex turn on GPT-6.2 Sol or GPT-6.2 Astra. The message names the model.

Cause. The Codex CLI installed on this computer is older than 0.166.0, or the ChatGPT plan behind the account doesn't include that model. AgentGrid runs the Codex CLI you installed, so the CLI's version decides which models work.

Fix. Update your Codex CLI to 0.166.0 or newer (Settings → Agents offers the update), then send the message again. If the CLI is already current, pick another model or a Codex account whose plan includes GPT-6.2.

"Screenshot capture failed — see main log for the CDP failure"

An agent sees this when it screenshots a browser pane and gets no image back.

Cause. Common causes:

  • The page isn't being drawn. AgentGrid is minimized, fully covered by another window, or running in a VM or remote session nobody is viewing. With nothing painted, there's nothing to capture.
  • DevTools is open on that browser pane. The capture can't attach while DevTools holds the page.

Fix. Keep the AgentGrid window visible and uncovered, close DevTools on that pane, then ask the agent to try again. If it still fails, close and reopen the browser pane, or restart AgentGrid. If it keeps failing, export diagnostics from the tray menu (on macOS, right-click AgentGrid's Dock icon) and send us the file.

Browser sign-in on this computer

For Claude, Codex, Cursor, Grok and Kimi running on this computer, sign-in from the desktop interface finishes in your browser with status shown in AgentGrid. Cursor, Grok and Kimi no longer open a terminal for this local flow. A floating status pill shows progress when you start sign-in from the account action; Settings and pane notices also show sign-in controls.

Use Open link again if the browser did not open, and enter any labelled Code: on the provider's browser page. Cancel stops the attempt; Try again starts a new attempt after a failure. A sign-in that takes too long asks you to try again. Sign-in for an agent running on a remote host still opens a terminal on that host, so you sign in where the agent runs.

For Claude's paste-code prompt, follow the steps below: its browser verification code and final authorization code go in different places.

"Sign in to continue: Your Claude session expired"

You'll see this card in a Claude pane instead of a reply.

Cause. Claude's sign-in on this computer expired and couldn't be refreshed. If the pane uses a token from Settings, the card asks you to replace the token instead.

Fix. Select Sign in to Claude and finish signing in in your browser. If claude.ai asks for a 6–8 digit verification code, enter it on that browser page, approve access, then paste the authorization code from the final page into AgentGrid. A rejected authorization code shows an error beside the input; correct it and submit again. For a token, select Replace token, paste a new one, then retry your message.

"Codex account isn't signed in or its session expired"

You'll see this notice in a Codex pane instead of a reply. It names the account.

Cause. The ChatGPT sign-in Codex uses on this computer expired.

Fix. Select the sign-in action on the notice and finish signing in, then retry your message. Or continue on another signed-in Codex account from the same notice. The account reads Sign-in expired in the account pickers, and automatic account selection skips it until it signs in again.

Settings also shows Sign-in expired with Sign in again when a Codex usage check discovers a rejected sign-in, before you send another message. A successful check or signing in again clears the expired state.

"Can't save sign-in: disk full"

AgentGrid keeps your refreshed desktop sign-in in memory and retries saving it. Free disk space so it can save before you quit or restart; an unsaved sign-in may not survive a restart. If a refresh is rejected, the sign-in screen explains why you need to sign in again.

Pro is still locked after checkout

Return to the desktop app after checkout. AgentGrid refreshes your access and retries briefly if payment confirmation is still arriving. Account settings and calling update without restarting. If access remains locked, check that checkout used the same AgentGrid account and that payment completed.

MCP shows "Failed to connect" after repeated checks

On macOS and Linux, short-lived clients such as Claude's MCP server-list check release their AgentGrid connection when they exit. On Windows, closing the client's input cleanly also releases the connection, but forcibly stopping its launcher can leave a slot occupied until it expires after 30 minutes of inactivity. If connection slots run out, restart AgentGrid to clear them sooner, or wait for them to expire. This recovery still applies to forcibly stopped launchers on current Windows builds.

"Not delivered" or "Unsent message"

You'll see Not delivered · Retry on a worker message that never started a turn. Team lead messages can also show Not delivered; during session recovery, a lead can instead show an Unsent message notice with Retry unsent message.

Cause. The agent stopped, restarted or lost its session before it could read the message. Your text, and any attachments, are kept. An Antigravity team lead in a terminal pane gets its first task only once its prompt is ready; if no prompt appears within 30 seconds (for example, it is still signing in or a trust dialog is open), the task is reported as not delivered.

Fix. Select Retry (or Retry unsent message) to resend the original text and attachments, or dismiss the message if you no longer need it.

"Turn interrupted"

You'll see a compact Turn interrupted row at the end of a conversation.

Cause. The turn stopped before it finished, because you stopped it, the app restarted, or the agent's process ended. What it already wrote stays in the transcript.

Fix. Select Continue to resume the turn where it left off.

"… can't see images, so the attached image won't reach it"

You'll see this warning in the composer after attaching an image.

Cause. The model you picked only reads text.

Fix. The message still sends without the image. If the image matters, pick a model that can see images first.

"… failed to start"

You'll see a turn notice such as Codex failed to start, followed by the reason and what to do next.

Cause. The coding agent (Claude, Codex and so on) couldn't launch: it isn't installed or signed in, its account was removed, or it exited straight away. The pane and its history are kept.

Fix. Read the reason shown in the notice and fix it (install or sign in under Settings → Agents), then send the message again. If you start a replacement pane instead, keep this one until the replacement is running, as the notice suggests.

"Cannot isolate Codex MCP configuration"

You'll see this when a Codex turn fails straight away. The text in brackets after it says what went wrong.

Cause. AgentGrid couldn't read Codex's configuration before starting it. One cause is a missing Codex home folder (~/.codex, or the home of a Codex account you added): the brackets say Codex home directory missing. Others are Codex not being installed (codex binary not found), a project folder that no longer exists (working directory not found), a Codex config.toml that doesn't parse (config parse error), or Codex taking too long to answer (timed out).

Fix. For a missing home folder, update to AgentGrid 2.9.46 or later, which creates the folder before starting Codex. For the other causes, install Codex, reopen the pane in a folder that exists, fix the line config.toml names, or retry once Codex responds. If a pane still says Failed to start with EEXIST or a permission error, something else is in the way at that path, such as a file named .codex; move it aside or fix its permissions, then select Retry in a terminal pane, or send the message again.

"Selected account was removed"

You'll see Selected account was removed; choose an account before continuing.

Cause. The pane was pinned to an account you've since removed. On the desktop, if you've picked a default account for that coding agent, or only one account is left, AgentGrid moves the pane to it automatically. With several left and no default, it can't guess which one you want. In the model picker the old entry shows as Removed account. A headless server refuses a removed or unlisted pinned account instead of silently choosing another; restore its account configuration before continuing.

Fix. Open the model picker on that pane and choose an account. See Multiple accounts per harness.

macOS asks to let AgentGrid control another app

You'll see a macOS prompt saying Agent Grid needs to control other apps when a worker uses macOS automation, for example sending or reading Messages.

Cause. A worker tried to script another app, such as Messages, and macOS asks once per app.

Fix. Select Allow if you expected it, or Don't Allow if you didn't. You can change it later in System Settings → Privacy & Security → Automation.

The phone app can't reach your computer

The iPhone app explains what's wrong, for example Phone access isn't ready on this computer — open AgentGrid → Settings → Devices, or that AgentGrid's background service isn't running.

Cause. The phone reaches your computer through the AgentGrid relay. It needs AgentGrid running on the computer, signed in to the same account, with the background service on and the relay connected.

Fix. Do what the message says. Settings → Devices warns you if the relay isn't working. Settings → Advanced → Keep workers and terminals running in the background must be on. If the phone says Update AgentGrid on your computer to connect, update the desktop app. See Coordinator → Your phone.

"Couldn’t load projects" on the phone

After reconnecting, the phone may still show saved projects while waiting for fresh project data. If that data does not arrive, Couldn’t load projects and Retry appear even with saved projects on screen. Select Retry to request the project lists again. If the data remains too large to reach the phone, retrying may still fail; this change makes the recovery action available, without removing that size limit.

A phone image preview stays missing after reconnect

Returning to the phone app can replace its connection to your computer. Interrupted requests are cleared so a later visit can request the image again. Once connected, leave the chat and reopen it to retry a missing thumbnail. The desktop still needs to be online and able to read the image.

Settings changes did not save

Settings saves only the choices you changed, so another open Settings window cannot overwrite unrelated choices. If saving fails, the footer shows the error with Try again. Use Try again to save the changes; Settings stays open if saving fails.

Setup AI says the model service needs attention

A model-service payment refusal is different from using your daily free credits. Contact support or follow manual coding-tool setup; waiting for tomorrow’s free-credit reset does not resolve the service refusal.

A worker could not be archived

The message names the boundary that failed, such as a missing window, a stopped response, unavailable archive data or a pane that disappeared. Let the space’s archive data finish loading and try again. A background close can wait longer while archive data loads; an unsuccessful close keeps its error visible.

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.