Skip to content

Troubleshooting

View as Markdown

Start with the CoAgent's detail page in Admin. Check its computer state and AI connection, then select View activity.

CoAgent is not responding

  1. Confirm it received work through a supported notification or assignment. A document mentioning a CoAgent does not itself schedule execution.
  2. Check whether the CoAgent is paused. Resume it if automatic work should continue.
  3. Check the AI connection. Reconnect if needed, and check provider usage availability.
  4. Inspect activity and mailbox records.

These commands read saved information. Replace AGENT with the CoAgent's username or ID:

sh
socra agent get AGENT
socra agent activity AGENT
socra agent message list AGENT --status queued

To inspect the connection status, run:

sh
socra agent connection check AGENT

For a CoAgent on a shared ChatGPT or Claude connection, this returns the saved connection state without waking the computer. It does not prove that a new task will succeed. Use Check the result to verify a task.

For a Codex CoAgent using a local ChatGPT sign-in, the command performs a live runtime check and wakes the computer if needed. Resume the CoAgent first if it is paused. Starting a sleeping computer takes time. Claude Code has no equivalent local sign-in check.

For an expired sign-in, Reconnect required, or an unavailable connection, follow Connection troubleshooting.

CoAgent cannot access a resource

Check access for the CoAgent's own directory principal. Your access does not transfer to the CoAgent. Follow Access and credentials to verify each required Module, Issue, conversation, repository and Project. A working AI subscription connection does not grant resource access.

For external tools, check the credential's scope and whether the computer started after the secret was created or rotated. Never ask the CoAgent to print a secret to prove it exists.

Work stopped or failed

Read the activity and recorded error. Check source control, deployments, sent messages, or other external results before retrying: an interrupted delivery may have already performed some actions.

A failed computer, expired provider connection, or provider usage limit requires a different remedy from an application permission error.

A run succeeded but the issue is still open

Event acknowledgement records runtime completion. Closing an issue and communicating results are separate actions the CoAgent must perform in the relevant app.

Ask the CoAgent what remains, and clarify the completion criteria rather than assuming an open issue is a delivery failure.

The CoAgent reports the wrong model

Read the saved model configuration in Admin or with socra agent get AGENT. Codex uses changed settings on a new turn; Claude Code uses them on a new runtime session. Active work retains its existing settings. See When changes take effect.

The model's own description can reflect stale conversation instructions. Confirm a particular past turn through runtime metadata when investigating a mismatch.

See Events and execution for related guidance.

See also