Troubleshooting
Recover from authentication errors, busy sessions, and interrupted streams.
Keep the requestId from a failed API response when asking the operator to investigate. It identifies the request without exposing your key.
| Symptom or code | What to do |
|---|---|
unauthorized | Verify the product API key and service URL. The key may have been revoked. |
invalid_request | Check the error message for a field name, type, or allowed range. |
session_not_found / execution_not_found | Check the ID and owner credentials. Resources belonging to another owner are unavailable. |
session_not_running | Call session.resume() before executing commands. |
session_image_mismatch | Reuse the existing image or choose a new session name. |
execution_busy | Wait for the active command, or cancel it and observe its terminal state. |
agent_busy | Wait for the provided agent, or stop its request before starting other work. |
session_busy | Another lifecycle operation holds the session lease. Let it finish before retrying. |
body_too_large / output_limit | Reduce the payload or write large command results to a file. |
provider_unavailable | The operator must configure a model key for that provider. |
agent_not_configured | Ask the operator to set the default provider and model, or supply both fields in the request. |
agent_failed | Check provider/model configuration and service logs using the request ID. The request may also have been cancelled. |
service_unavailable | Inspect session and execution status before retrying an operation with side effects. |
Output stream disconnected
Save the execution ID and the last event sequence you processed. Reconnect with session.execution(id) and execution.events({after: lastSequence}). Starting a new execution would run the command again.
Aborting a fetch or losing the network does not confirm that a command stopped. Use execution.cancel() when cancellation is intended, then wait for a terminal state.
Command completion is uncertain
execution_unsettled means the service cannot confirm process termination. The session remains reserved to prevent a second managed command from overlapping it. The operator should inspect recovery status and the guest process before releasing that reservation.
File is missing after reconnect
Confirm that you reopened the same session ID and that the file was under /workspace. Files in the home directory belong to the retained VM disk. If the VM was replaced, those files require a separate restore or setup recipe.
A failed mount or a file API path that traverses symlinks can also cause a file operation to fail. File API operations reject symlink traversal. Use the shell deliberately when your project requires symlinks, and keep its writes in the intended session.
New writes may still have been buffered inside the old VM when it was lost. A readback from that VM only confirmed local availability. Review your application's fsync behavior and coordinate clean shutdown or replacement with the service operator. See Persistence.
Local package cannot be imported
Run the build before packing or invoking the CLI. For an external application, install both the contracts and SDK tarballs from the same checkout. See SDK installation.