Local runtime errors
Read error responses, identify the cause and restore operation.
This page covers the local console, HTTP API and MCP tools. For cloud HTTP statuses and troubleshooting, see cloud errors.
Read an error
MCP returns a structured result for known runtime conditions:
{
"ok": false,
"error": "calibration_required",
"hint": "open Devices > Calibrate in the web interface, confirm safety and finish coordinate calibration",
"detail": "..."
}| Field | Meaning |
|---|---|
error | Identifier for programmatic handling. |
hint | Suggested next action. |
detail | The specific device or runtime condition. |
Local HTTP endpoints usually return {"error":"reason"} and may include kind: "control_not_ready" for unmet control prerequisites. Other MCP exceptions may arrive as ToolError.
Runtime conditions
| error | Cause | Action |
|---|---|---|
not_alive | A camera, arm or gripper is unavailable. | Check connections, frame freshness and current device faults. |
control_not_ready | Control mode, ownership or a motion prerequisite is not ready. | Follow detail to select UR Remote mode, release Desk ownership or enable control. Return Home first if outside the motion range; direction trials also require Home. |
loop_running | The operation conflicts with the run state or owner. | Read state and stop before switching entry points or changing settings. |
calibration_required | Valid workstation calibration is missing. | Complete coordinate calibration, then enable control. |
calibration_action_failed | A capture, return or calibration step failed. | Follow the prompt. Failed returns retain samples; initialization failure after saving retains calibration. |
policy_unavailable | Model discovery, a session operation or inference failed. | Check Base URL, model ID, key and the model errors below. |
Model connection errors
The run record's error_kind provides more detail:
| error_kind | Action |
|---|---|
connect_timeout, transport_error | Check the host-to-service network, address and TLS. |
read_timeout | Keep the request ID and confirm request and robot state before deciding to retry. |
authentication_rejected | Use a valid API Key. |
not_authorized | Check the key's access to the selected model. |
model_unavailable | Choose an ID returned by /models at the same service. |
http_error | Use the HTTP status to consult the model service's error reference. |
invalid_response | Check session and response formats in Tasks and sessions. |
policy_unavailable, runtime_error | Read the detailed reason in the console and service terminal. |
Inference failure ends the run without automatic inference retries. After a timeout, confirm device and request state to avoid repeating actions.
Recovery actions
- Robot Stop interrupts controlled motion.
- Home opens the gripper and returns to the calibrated pose. Recover & Home recovers the device first. Both move the arm.
- HTTP
/api/errors/clearremoves historical error events and the stop reason while idle with devices available. It does not recover hardware.
Read current state after a failed request before choosing the next action. A stopped direction check does not return automatically; explicitly return Home before another trial. See frequently asked questions.
For support, include the version, time, entry point, error code and request ID. Run logs are stored under ~/.config/roboapi/logs/ by default. Do not include API Keys, Desk passwords or sensitive images.