Error reference
Common failures from the CLI and SDK, what they mean, and how to fix them.
Authentication
API key is required. Run 'reflex login' or set REFLEX_API_KEY.
No API key was found in any of the three resolution slots. Either:
reflex login
# or
export REFLEX_API_KEY=rfx_...See Authentication for the full resolution order.
401 Unauthorized / whoami exits non-zero
The key was found but the server rejected it. Most likely it was rotated or
revoked from the dashboard. Run reflex login again to fetch a fresh key.
Connection
Connection refused during ActionStream.open()
The server refused the connection. The SDK retries transient codes (403,
404, 408, 425, 429, 5xx) until connect_retry_seconds elapses
(default 90s). Other 4xx codes fail immediately.
401/403→ bad API key. See Authentication.404→ bad URL override. Drop any customurl=/--convex-urlflag.429→ over a rate limit. Back off and retry.
recv_action() times out
The connection has been alive for timeout seconds without sending an action
chunk. Common causes:
- Model is cold-starting. The default
timeoutis usually enough; raise it on the first call after a long idle period. - Network egress is dropping packets. Check
open_timingand any local network monitor.
Cannot reach the Reflex backend
The CLI was pointed at a custom backend with --convex-url or
REFLEX_CONVEX_URL and the address is unreachable. Unset the override or
fix it.
reflex connect
Deployment not ready for apply_actions
A deployment must pass a readiness check before it can drive hardware. Run
reflex doctor <deployment-id> and address each failed
check in the response, then retry.
Safe stop fired mid-run
The streaming session died mid-loop, so the runner brought the robot to a
known-safe state. After resolving the underlying network or server issue,
re-run reflex connect.
The observe command timed out
When using the subprocess hardware connector, your observe command did not
produce a JSON line within its command_timeout_s (a config field). Either
the command is too slow or it hung — profile the script; raise the timeout
only if the slowness is intrinsic.
Could not auto-detect an SO-101 serial bus
The SDK looks at common /dev/tty* names. If your arm isn't found, set the
port explicitly with the REFLEX_SO101_PORT environment variable:
export REFLEX_SO101_PORT=/dev/ttyUSB0Datasets and training
Training rejects an unvalidated dataset
Run reflex datasets validate <dataset-id> before starting training.
Training run stuck in queued
The training queue may be backed up — reflex training list --all will show
where your run sits. Cancel and retry with --request-id set to a new value
if you need to bump priority via a fresh run.
Sessions
Session is still in dry_run
Promote the session before it can apply actions:
reflex sessions promote <session-id> --to apply_actionsSession expired or already closed
The session expired or another process closed it. Start a fresh session.
Getting more detail
Add --verbose (or -v) to CLI commands for driver and transport logs.
Use --json to inspect the structured error response — the error field is
the first place to look.