ModuleNotFoundError: No module named 'isaaclab' — Isaac Lab 未安装
训练或评估以导入错误退出。Isaac Lab 不是 pip 依赖——必须按官方 Isaac Lab 安装指南单独安装，然后激活正确的环境（conda activate env_isaaclab）。
总表 · 来自官方文档
GR00T / SONIC 排错：错误总表
官方排错指南里的每一类错误，外加 MotionBricks 的 Known Issues——一页搞定，可搜索。如果你的问题不在这里，官方页面会指向 GitHub issues。
GR00T-WBC 技术栈错误
Mesh files are tiny text files — Git LFS 未安装
网格文件（.stl/.STL）约 130 字节，内容以 version https://git-lfs.github.com/spec/v1 开头——仓库是在没有 LFS 的情况下克隆的。修复：sudo apt install git-lfs；git lfs install；git lfs pull。核对 main.urdf 约 60KB+，而不是约 130 字节。
修复：
sudo apt install git-lfs && git lfs install && git lfs pullRuntimeError: size mismatch — Checkpoint 与配置不匹配
例如 'size mismatch for actor_module.decoders.g1_dyn.module.0.weight'——实验配置定义的网络架构与 checkpoint 不同。发布的 sonic_release checkpoint 使用 hidden_dims: [2048, 2048, 1024, 1024, 512, 512]。把你的配置对齐到 checkpoint 的 config.yaml。
TensorRT version mismatch — 静默错误的推理
TensorRT 版本与要求不符会产生静默错误的推理结果——模型正常运行不报错，但输出错误的动作。x86_64 桌面需要 TensorRT 10.13；Jetson / G1 板载 Orin 需要 10.7（JetPack 6）。用 echo $TensorRT_ROOT 和 ls $TensorRT_ROOT/lib/libnvinfer.so* 核对。
修复：
用精确版本：10.13（x86_64）/ 10.7（Jetson，JetPack 6）；从 NVIDIA Developer 下载 TARdeploy.sh fails to bind ZMQ port 5557 — Unitree iphone_server 服务冲突
在 Orin 上，Unitree 的系统服务（iphone_server.service）已经占用了 5557 端口。
修复：
sudo systemctl stop iphone_server.service（跨重启禁用：sudo systemctl disable iphone_server.service）ChannelFactory create domain error — CycloneDDS 域冲突
run_sim_loop.py 以 cyclonedds.domain.Domain 初始化错误崩溃——SimulatorFactory 重新初始化了一个已创建的通道。已知问题 #77：注释掉重复的通道初始化，或确保没有其他 DDS 进程使用同一个域。
MuJoCo viewer black in Docker — Intel iGPU / NVIDIA dGPU 冲突
Intel 显示控制器机器上，Docker 内的 MuJoCo 窗口黑屏或花屏。修复：强制 NVIDIA 渲染（__NV_PRIME_RENDER_OFFLOAD=1、__GLX_VENDOR_LIBRARY_NAME=nvidia），或加 --gpus all -e DISPLAY=$DISPLAY 运行。见 issue #25。
SMPL tracking unstable / drifts — 坐标系约定不匹配
SMPL 数据可能有约定不匹配（y-up vs z-up）、关节顺序错误或重定向质量差。y-up 时核对 smpl_y_up: true；检查 SMPL PKL 的 smpl_joints 形状为 (T, 24, 3)；也可以先用 smpl_motion_file: dummy 隔离机器人编码器。
Robot explodes / falls on first frame — 初始状态或增益错误
通常是其中之一：init_state.pos 的 z 高度错误、KP/KD 太低或太高、动作尺度太大、默认关节角错误。用 num_envs=1 headless=False 调试，观察前几帧。
RuntimeError: body 'xxx' not found — 配置引用了不存在的 body
配置 YAML 引用了你的机器人上没有的 body 名（把 G1 配置用在 H2 等不同机器人上时常见）。在 gear_sonic/config/ 里 grep -rn 报错的 body 名并覆盖它，或看 new embodiments 指南。
更多：官方完整清单还覆盖 trl/transformers 版本冲突、动作文件路径错误与 body 名配置——直接阅读原文。
MotionBricks 已知问题（README）
- Linux/X11 only: The keyboard key-grab workaround requires X11 (python-xlib). On Wayland, macOS, or Windows, some MuJoCo keyboard shortcuts may conflict with the controller keys. Keep the terminal focused (not the MuJoCo window) as a workaround.
- PYTORCH_JIT=0 disables key grabs: Running with PYTORCH_JIT=0 interferes with the X11 key-grab workaround. If you need PYTORCH_JIT=0, keep the terminal focused instead.
- Keyboard package differs by OS: The pynput package is required for keyboard input on Linux/macOS. On Windows, the keyboard package is used instead.
排错常见问题
为什么我的 G1 网格文件只有约 130 字节？
克隆前没装 Git LFS——这些网格是 LFS 指针。运行 sudo apt install git-lfs、git lfs install，然后 git lfs pull，并核对 main.urdf 约 60KB+，而不是约 130 字节。
为什么我的 SONIC checkpoint 在真机上行为错误、在仿真里却正常？
TensorRT 版本不匹配是典型原因：TensorRT 版本与要求不符会产生静默错误的推理结果。x86_64 桌面精确用 TensorRT 10.13，Jetson / G1 板载 Orin（JetPack 6）用 10.7，然后重新编译 C++ 部署二进制。
加载 checkpoint 时报 size mismatch 错误是什么意思？
实验配置定义的网络架构与 checkpoint 训练时用的不同——常见于覆盖 hidden_dims。把你的配置对齐到 checkpoint 保存的 config.yaml；发布的 sonic_release checkpoint 使用 hidden_dims [2048, 2048, 1024, 1024, 512, 512]。
仿真一开始机器人就立刻摔倒——为什么？
通常是其中之一：初始状态高度错误（init_state.pos 的 z 值）、KP/KD 值不对（太低=没有保持力矩，太高=不稳定）、动作尺度太大、默认关节角错误。用 num_envs=1 headless=False 调试，观察前几帧。