Troubleshooting & FAQ

Common issues when bringing up or operating the closed-loop stack.

The backend won’t boot

Check GET /diagnostics/boot — it surfaces boot-time errors (a missing config, an unreachable device, a bad connections.json entry). Confirm the backend is the kcare_robot FastAPI app on :8001 and that the active location’s connections.json is valid.

No devices / ROS not connected

  • Make sure the ROS2 stack (Humble) and the robot’s drivers are up on the control machine, and ROS_DOMAIN_ID matches.

  • In the dashboard’s DevicePanel, scan ROS interfaces and verify each agent in connections.json resolves to a live topic/service/action.

  • Switching the location triggers a reconnect — use it to re-establish devices after the robot drivers restart.

VisionServe / detection fails

  • Verify the VisionServe server is running and reachable at :11435 (the client checks health on connect).

  • find returns nothing → check the text prompt and that the requested model (grounding-dino / grounded-sam / grasp-gd) is served.

  • Detections look mislocated → suspect the head-to-base calibration, not the detector.

Planning / LLM problems

  • “planner unavailable” → pyplanner must be installed (pip install -e pyplanner) for the grace backend.

  • The model is slow or unreachable → confirm the LLM backend (POST /agent/llm-config) and that Ollama (:11434) or the API key is set.

  • Plans keep failing verification → inspect the per-run JSONL in task_runs/; the failing layer (isdone / symbolic / VLM) is recorded per step.

Grasping issues

  • holding shows the wrong object — there is no gripper sensor; it is a belief. Correct it from the dashboard’s Robot State (PUT /agent/world).

  • A grasp uses an old pose — if found_pose is flagged stale (base moved > 0.25 m since detection), re-run find before picking.

Replanning never finishes

Replans are bounded (default 3). If a task exhausts the budget it ends with status = failed — read the run log to see which sub-goal could not be repaired, and check that the precondition the verifier complains about is actually satisfiable on this robot.

Voice / TTS

The Announcer speaks milestones in vi / ko / en. If Vietnamese audio falls back to English on the backend, that is the known TTS clamp; the dashboard’s browser-side speech can still speak vi-VN.

Two operators conflict

If the robot behaves erratically, make sure only one client is commanding it. The dashboard and the CLI both resolve to POST /skill/<name>; running them against the same robot at once is unsafe.