Troubleshooting by symptom
| Symptom | First checks | Next layer |
|---|---|---|
| Console unavailable | Host reachability, listener/port, systemd status | Console journal, package/frontend paths, proxy |
| Console works, SDK stopped | Selected operator/config/release and task results | CLI validation, Docker, launch script logs |
| Frontend loads, robot controls fail | WebSocket and ROS adapter status separately | Redis/bootstrap/config manager and ROS services |
| Settings apply then revert | Command result and authoritative runtime values | Saved override/source precedence and restart behavior |
| Live settings work, Save fails | Manager result/timeout | Writable storage, selected target, config manager |
| Speech ping works, synthesis fails | Application response.error, loaded voice |
Provider credentials/license/network/config |
| Audio generated, mouth static | ROS speech/viseme paths | Blender/audio2lips and selected animation rig |
| Browser microphone gives no text | Permission, ownership, lease, PCM rate | ASR enable/input/provider/gating and credentials |
| Browser speaker works, robot silent | Monitor versus internal/physical output | PulseAudio routing, mounted socket/cookie, output choice |
| Perception local, robot sees no people | Domain, interface routes, message types/QoS | Publisher/subscriber graph and fusion output |
| Camera visible, depth targets wrong | Alignment and camera info | Transform/calibration/frame conventions |
| Uploaded face not recognized | embedded result and quality reason |
Extraction service, threshold/model and identity feedback |
| Regeneration loses matches | Partial failure list | Cleared old embeddings and unavailable extraction |
| Unity blank | Loader/data/WASM HTTP and encoding | WebGL startup/browser errors |
| Unity loads, no animation | /unity_wss handshake and packet rate |
Streamer/PAU output and packet/rig mapping |
| Manual motor value overridden | Control mode and other publishers | Behavior/attention/animation ownership |
| Servo scan empty | Power, port, permissions, baud/family | Exclusive bus access and configured IDs |
| Performance editor disagrees with playback | Dirty draft/storage/runtime revisions | Current payload, stale tick filtering and command result |
| Update appears stuck | Exact task handle/stage/logs | Download/process state and installer resumption |
Collect evidence before retrying
Record the time, robot identity, selected release/configuration, endpoint/command, request ID/task ID and actual result. Capture service status and narrowly scoped logs. Avoid broad environment/config dumps that can expose credentials.
systemctl status hrsdk.service hr-system-console.service --no-pager
journalctl -u hrsdk.service -n 100 --no-pager
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
ip -brief address
ip route
df -h
A timeout is not cancellation. Check current state before repeating a motion, speech, provisioning, update or install action. Reloading a browser does not necessarily stop server tasks or ROS execution.
Read-only remote isolation
Start with API health, resource/state/catalog reads and graph inspection. Then check required provider/device dependencies. Use narrow functional tests only after understanding their effects. The source contract can explain intended behavior; hardware/provider acceptance still needs the real deployment.
Refer to the relevant service catalog for detailed errors and recovery paths. Backup/restore and update/rollback provide durable recovery steps.