Troubleshooting

The workspace is asleep

Sleeping saves the workspace and stops its machine about ten minutes after the agent goes idle. Send a message or choose Wake workspace in thread details to resume. Keeping the thread or terminal open does not keep it running; background work the agent started may hold it awake for a while.

Setup failed

Expand the setup command in the transcript and read its output. Check the repository's .agents/setup and .agents/services.yaml, dependency access and the secrets the setup needs. Ask the agent to fix the failing step; repeating a command without fixing its cause will not repair it. For a saved environment, read its setup output in Settings → Environments and Retry. See Project environments.

A thread looks stuck

Check its latest transcript activity and any open question: Needs you means the agent is waiting for your answer. A provider limit shows when it resets; choose Resume at reset or reconnect an expired connection in Settings → Agent connections. Use Stop to interrupt active work, then send a new message.

The thread says Limited

Limited means a provider usage limit, no credits, or a suspended account. The banner says which. Add credits in Settings → Billing, wait for the provider reset, or contact support.

The machine ran out of memory

Thread details show memory and disk use and, after an out-of-memory stop, the largest processes. Choose Move to bigger machine when it is offered. standard-4 is the largest size; on it, run fewer processes at once. A larger machine uses credits at its own rate. See Credits and machines.

A preview does not load

Make sure the app listens on the port you opened, on all interfaces, and that the port is between 1024 and 65535 and not 4096, 4500 or 9229. A sleeping workspace shows a wake page first.

A CLI command cannot find the thread

Run statefold config and statefold account to check the target and account, then statefold doctor. Threads belong to one account on one target. A thread missing on another target is not a reason to upload the workspace again.

An API call fails

Read error.code in the response; Errors lists each code and whether to retry.

Still stuck

Get support with the thread link and the approximate time.