Master table · from official docs

GR00T / SONIC troubleshooting: the master table

Every error class from the official troubleshooting guide, plus the MotionBricks Known Issues — one page, searchable. If your problem isn't here, the official page points to GitHub issues.

GR00T-WBC stack errors

ModuleNotFoundError: No module named 'isaaclab' — Isaac Lab not installed

Training or eval exits with an import error. Isaac Lab is not a pip dependency — it must be installed separately following the official Isaac Lab install guide, then activate the correct environment (conda activate env_isaaclab).

Mesh files are tiny text files — Git LFS not installed

Meshes (.stl/.STL) are ~130 bytes containing version https://git-lfs.github.com/spec/v1 — the repo was cloned without LFS. Fix: sudo apt install git-lfs; git lfs install; git lfs pull. Verify main.urdf is ~60KB+, not ~130 bytes.

Fix: sudo apt install git-lfs && git lfs install && git lfs pull

RuntimeError: size mismatch — Checkpoint vs config mismatch

e.g. 'size mismatch for actor_module.decoders.g1_dyn.module.0.weight' — the experiment config defines a different network architecture than the checkpoint. The released sonic_release checkpoint uses hidden_dims: [2048, 2048, 1024, 1024, 512, 512]. Match your config to the checkpoint's config.yaml.

TensorRT version mismatch — Silently wrong inference

A different TensorRT version than required produces silently wrong inference results — the model runs without errors but outputs incorrect actions. x86_64 desktop requires TensorRT 10.13; Jetson / G1 onboard Orin requires 10.7 (JetPack 6). Verify with echo $TensorRT_ROOT and ls $TensorRT_ROOT/lib/libnvinfer.so*.

Fix: Use exact versions: 10.13 (x86_64) / 10.7 (Jetson, JetPack 6); download TAR from NVIDIA Developer

deploy.sh fails to bind ZMQ port 5557 — Unitree iphone_server service conflict

On Orin, a Unitree system service (iphone_server.service) already listens on port 5557.

Fix: sudo systemctl stop iphone_server.service (disable across reboots: sudo systemctl disable iphone_server.service)

ChannelFactory create domain error — CycloneDDS domain conflict

run_sim_loop.py crashes with a cyclonedds.domain.Domain init error — the SimulatorFactory reinitializes a channel already created. Known issue #77: comment out the duplicate channel init, or ensure no other DDS process uses the same domain.

MuJoCo viewer black in Docker — Intel iGPU / NVIDIA dGPU conflict

Black or garbled MuJoCo window inside Docker on Intel display controller machines. Fix: force NVIDIA rendering (__NV_PRIME_RENDER_OFFLOAD=1, __GLX_VENDOR_LIBRARY_NAME=nvidia) or run with --gpus all -e DISPLAY=$DISPLAY. See issue #25.

SMPL tracking unstable / drifts — Coordinate convention mismatch

SMPL data may have mismatched conventions (y-up vs z-up), wrong joint ordering, or poor retargeting. Verify smpl_y_up: true if y-up, check SMPL PKLs have smpl_joints shape (T, 24, 3), and try smpl_motion_file: dummy first to isolate the robot encoder.

Robot explodes / falls on first frame — Init state or gains wrong

Usually one of: wrong init_state.pos z-height, KP/KD too low or too high, action scale too large, or wrong default joint angles. Debug with num_envs=1 headless=False and watch the first frames.

RuntimeError: body 'xxx' not found — Config references a missing body

A config YAML references a body name that doesn't exist on your robot (common when using G1 configs with a different robot like H2). grep -rn the failing body name in gear_sonic/config/ and override it, or see the new embodiments guide.

More: the full official list covers trl/transformers version conflicts, motion file path errors, and body name configs — read it directly.

MotionBricks known issues (README)

Troubleshooting FAQ

Why are my G1 mesh files only ~130 bytes?
Git LFS was not installed before cloning — the meshes are LFS pointers. Run sudo apt install git-lfs, git lfs install, then git lfs pull, and verify main.urdf is ~60KB+, not ~130 bytes.
Why does my SONIC checkpoint give wrong robot behavior on the real robot but works in sim?
TensorRT version mismatch is the classic cause: a different TensorRT version than required produces silently wrong inference results. Use exactly TensorRT 10.13 on x86_64 desktop and 10.7 on Jetson / G1 onboard Orin (JetPack 6), then rebuild the C++ deployment binary.
What does a size mismatch error when loading a checkpoint mean?
The experiment config defines a different network architecture than the checkpoint was trained with — often from overriding hidden_dims. Match your config to the checkpoint's saved config.yaml; the released sonic_release checkpoint uses hidden_dims [2048, 2048, 1024, 1024, 512, 512].
The robot falls over instantly when simulation starts — why?
Usually one of: wrong init state height (init_state.pos z-value), KP/KD values wrong (too low = no holding torque, too high = unstable), action scale too large, or wrong default joint angles. Debug with num_envs=1 headless=False and watch the first frames.