Guide
Troubleshooting·
Symptom → cause → command, for the eight things that actually go wrong: daemon unreachable, motors off, first-call hangs, no camera, silent voice, import-ok-but-nothing-runs, odd poses.
In 10 seconds
- Every tool returns an error string, never a traceback — its first line names the layer.
- Check in order: daemon → motors → media → keys.
- On the robot the units restart themselves; read why in
journalctlbefore touching anything. - Voice back-off: a fatal provider error doubles the delay 5 → 300 s; transient ones retry in 5 s.
Cannot connect to the daemon·
Wrong host, or no daemon.
- Lite:
REACHY_CONNECTION_MODE=auto(localhost:8000) - Wireless:
REACHY_HOST=reachy-mini.local,REACHY_CONNECTION_MODE=network - No robot:
make sim
Motors will not move·
Disabled or in gravity-comp:
> check state # reachy_get_state → look at motor mode
> enable your motors # reachy_motors('enabled')
reachy_express hangs on first call·
The emotion library is downloaded live the first time, then cached.
Camera returns nothing·
The daemon owns the camera. If grabs conflict:
REACHY_MEDIA_BACKEND=no_media # let reachy_camera grab transiently
REACHY_CAMERA_BACKEND=local # backend used for transient grabs
Voice persona is silent·
Then OPENAI_API_KEY in .env. On the robot, read the unit:
| you see | it means | do |
|---|---|---|
Temporary failure in name resolution |
booted before DNS | nothing — retries in 5 s |
[Errno -9985] Device unavailable |
daemon still bringing audio up | nothing — retries in 5 s |
invalid_api_key / 401 |
the key in .env |
fix it, systemctl --user restart tiny-voice |
| you cannot interrupt it | XMOS PP_NLATTENONOFF=1 (factory) mutes you while it speaks |
VOICE_XMOS_PARAMS is re-applied at every start |
A mid-conversation restart takes ~90 s.