Troubleshooting

Troubleshooting#

Installation Stops During a Build#

install.sh aborts on the first failed build. Both common failures are missing system packages from System Prerequisites:

Message

Install

build.sh: line 25: cmake: command not found

build-essential cmake

fatal error: Python.h: No such file or directory (building evdev)

python3-dev

Install the package and rerun the same install.sh command. Completed steps are detected and skipped, so the XRoboToolkit clone and native build are not repeated.

Device or Port Missing#

handumi setup ports
lsusb
ls /dev/ttyACM* /dev/ttyUSB*

Reconnect one device at a time. Log out and back in after serial-group changes.

Adapter visible in lsusb but no serial port exists

Common Feetech adapters use the CH341 driver. Check the running kernel and installed module tree:

uname -r
modinfo ch341
ls /usr/lib/modules/$(uname -r)

If the module tree does not match the running kernel, reboot after the system update, reconnect the adapter, and rerun handumi setup ports.

Quest Does Not Stream#

Keep HandUMI Quest App in the foreground, confirm both devices share a network, update quest_ip in configs/rig.yaml, and wake both controllers.

PICO Does Not Stream#

Confirm the PC service and headset stream are running. For USB, check:

adb devices
adb reverse --list

Gripper Width Is Wrong#

Confirm side/port mappings, then run the unified calibration. It guides you through mid-travel homing, full opening, and full closure:

handumi calibrate grippers

If left/right motion is swapped, correct the mapping in configs/rig.yaml; do not compensate by reversing calibration values. If a camera appears twice, test the first /dev/video* node associated with that physical device.

Voice Control Does Not Respond#

Check what the recorder is listening to:

handumi doctor

If the microphone is the wrong one, name it explicitly with --voice-device <name-or-index>; the default follows the system input, so a headset only takes over once the OS has switched to it. If commands are heard but ignored, the phrase must be exactly “start recording”, “stop recording”, or “restart” — nothing else is in the recognizer’s vocabulary. Lower --voice-confidence if a correct phrase is still being dropped, and raise it if the room is noisy enough to trigger commands on its own.

To record without voice, use --no-voice-control, and add --clap-control to keep a hands-free control through gripper squeezes.

Recording Is Rejected#

Inspect meta/handumi_quality.json. The common causes are tracking loss, stale cameras, synchronization errors, frozen poses, large motion jumps, or an episode that is too short.

Replay Prints a CUPTI Traceback#

If JAX reports Unable to load cuPTI but replay continues, force the supported CPU path for the command:

JAX_PLATFORMS=cpu uv run handumi replay \
  outputs/20260714_224135 \
  --robot openarmv1 \
  --episode 0

This warning concerns optional CUDA profiling libraries, not the dataset or robot IK.

Dataset Video Loading Fails in TorchCodec#

A traceback ending in Could not load libtorchcodec, libavutil.so.*, or libavdevice.so.* occurs while LeRobot opens the dataset’s MP4 features. It happens while a command decodes camera video and does not by itself indicate a damaged dataset. Current trajectory replay reads the Parquet state columns without opening MP4 files, so a plain handumi replay should not require TorchCodec. Report a replay traceback if it still enters decode_video_frames.

On Ubuntu/Debian, install the system FFmpeg package:

sudo apt update
sudo apt install -y ffmpeg

Confirm that the executables and TorchCodec loader work:

ffmpeg -version
ffprobe -version
uv run python -c "from torchcodec.decoders import VideoDecoder; print('TorchCodec OK')"

Errors for FFmpeg major versions that are not installed are expected in the expanded TorchCodec traceback. Inspect the block for the installed version; on Ubuntu 24.04 the repository package is FFmpeg 6 and provides, among the other runtime libraries, libavdevice.so.60.

This video-runtime failure is unrelated to a preceding message such as Uninstalled xrobotoolkit-sdk. A standalone uv sync --extra sim may remove that locally installed PICO package because it is not part of the portable lockfile. Replay does not use XRoboToolkit. Run bash install.sh --sim later if the same workstation must retain or restore PICO capture support.

Viser Shows Trajectories but No Robot#

Messages such as Can't find meshes/visual/base_link.glb mean the URDF loaded but its visual asset paths did not resolve. Restart replay after updating the checkout. TRLC-DK1 meshes must exist under:

assets/trlc-dk1/meshes/visual/
assets/trlc-dk1/meshes/collision/

Run this check from the repository root:

JAX_PLATFORMS=cpu uv run python -c \
  "from handumi.robots.registry import load_embodiment; u=load_embodiment('trlc_dk1').load_urdf(load_meshes=True); print(len(u.scene.geometry))"

The current GLB assets expand to hundreds of internal submeshes; a nonzero count without Can't find messages confirms that the visuals loaded.

Piper CAN Is Down or BUS-OFF#

This applies only to physical Piper teleoperation. Check robot power and wiring, then follow the CAN checks in Piper Hardware Setup.

Piper Real Arms Do Not Start#

Test simulation first, verify both controllers are tracked, confirm CAN is up, and use --side right for the first hardware check. See First real teleoperation for the complete startup sequence.