Frequently asked questions
Find solutions by symptom and restore device connections and task execution.
The local console will not open
Activate the installation environment on the control computer and run roboapi http. The default address is http://127.0.0.1:8080/. To connect from another computer, set up SSH forwarding as described in installation.
If configuration is missing, run roboapi init first. Use roboapi http -c /path/to/config.yaml for a custom file. If UR e-Series reports a missing native executable, complete UR runtime installation in the same environment.
An adapter is missing from setup
Install the adapter in the same Python environment as RoboAPI, then restart. Read the load error printed by setup and install the declared SDK dependencies. Names within a component group must not conflict. A configuration selecting an adapter that cannot load fails with its load error. See Hardware adapter interfaces.
An upgrade reports missing installation details or tool load
Stop the service and run roboapi init --complete in the existing environment. Add -c /path/to/config.yaml for another configuration path. For Franka, select matching standard assembly data or enter a custom load. For URCap, provide the actual controller address. Recalibrate before enabling control if completion reports a changed connection identity. See Versions and upgrades.
No camera image
Distinguish a browser preview interruption from the control computer receiving no frames. The page attempts to reconnect a stalled preview; if device status still shows fresh frames, reopen the page. If the camera device is also unavailable:
- Check USB video mode and a data-capable cable.
- Check the capture-device path, permissions and whether another program is using it.
- Confirm MJPG 1280×720 at 30 FPS support.
v4l2-ctl --list-devices
ls -l /dev/v4l/by-id/Set camera.device to the actual capture node. After video recovers, explicitly restart any stopped task.
For cropped edges, use Show full frame. For a hidden view, use the camera icon. Browser cropping and hiding do not affect model images or recordings.
Video works but tasks cannot start
Under Settings → Devices, check saved calibration, enabled control, arm and gripper connections, then check the model connection. A workstation with saved calibration still needs control enabled after restarting.
If the robot is outside the motion range, return Home first. Stop an Agent-owned run before starting from the browser. See the local console.
Calibration cannot return or finish
Keep A/B/C on one level surface and off a single line, with Home above the surface. Preserve tool orientation and the contact point during capture.
- UR e-Series: switch to Remote before automatic returns.
- Franka: release other Desk control owners and configure the real-time host and tool according to deployment.
- Return fails: samples remain; resolve the prompt and choose Retry.
- Enabling control fails after saving: calibration is retained; resolve the prompt and enable control again.
Use Previous step to recapture the latest point without moving the arm. Closing the dialog allows you to resume later; Disconnect discards unfinished teaching. See coordinate calibration.
A direction check did not return after Stop
This is expected: Stop cancels the remaining trajectory, including the return. Use the check panel's return action before another direction. Each trial starts at Home and physically translates 5 cm and rotates 30°; it does more than display an animation.
The robot reaches the boundary but keeps running
The default motion range extends 60 cm from Home in both directions on each axis. Targets outside the range are clipped to its boundary while the policy continues. Use Robot Stop to end the task. Change the range under Settings → Devices → Motion range while idle after finishing calibration.
The range limits commanded flange-centre position, not the entire arm or rotation, and does not provide obstacle avoidance. See motion range.
Model connection fails
| Symptom | Action |
|---|---|
| 401 / 403 | Check the API Key's validity and model permissions. |
| Empty model list | Check that the key has model access at this service, then select Connect again. |
| Previous model unavailable | Check the address and key, retrieve the list again, and select an available model. |
| Cannot connect | Confirm that the Base URL is the official service address, https://api.pokebot.com/v1, then check the network, DNS and proxy from the control computer. |
invalid_response | Check the local runtime protocol, including sessions, execution receipts and action format. |
Setup also needs network access to retrieve models; follow the wizard's retry prompts if connection fails. After changing the address or key in the console, Connect again, select a model, then Save. Failed connection or save attempts preserve the saved configuration.
An inference failure during a run ends that run. After a timeout, confirm robot and request state before starting again.
A new instruction did not start
Typing or selecting a preset only changes the draft. Send or press Shift+Enter to execute; Enter inserts a line break.
Sending a non-empty browser draft during a run stops the current run and starts a new task. Updating an active instruction over HTTP or MCP takes effect at the next inference without interrupting the current action chunk. Use Robot Stop for an immediate stop.
A recording will not download or a task cannot be deleted
Video may still be saving after a task stops. Wait for it to finish before replaying or downloading. Running tasks and tasks saving video cannot be deleted; batch cleanup skips them.
Clear recordings keeps instructions, ratings and notes. Delete tasks removes all of them. Storage belongs to the control computer; changing browsers does not free its disk space.
Clearing historical errors did not recover the device
The HTTP clear-errors operation only removes historical error events and the stop reason. It does not recover a device.
Resolve the current connection, control-owner or robot fault. Use Recover & Home when device recovery is needed; it moves the arm. Home also moves the arm and opens the gripper.
For support, include the version, time, entry point, error code and request ID. Do not include API Keys or Desk passwords. See local runtime errors or cloud HTTP errors.