Troubleshooting

Troubleshooting#

Quick fixes for the errors people hit first. Still stuck? Open an issue.

No tasks in wbc-mjlab-list-envs#

Symptom: empty list, or only unexpected ids.

Checks:

  1. Install the package in the active env (make sync / uv sync).

  2. Extension robots: install the extension editable and confirm [project.entry-points."mjlab.tasks"] points at your mjlab_entry.

  3. Re-run uv run wbc-mjlab-list-envs after install.

See Extensions.

No clip NPZs / empty motion library#

Symptom: train/play fails looking for npz/*.npz.

Fix: convert first:

uv run wbc-mjlab-data-to-npz --robot g1 --dataset samples --batch-size 8

Confirm files exist under data/<robot>/<dataset>/npz/. Layout: Motion data.

Joint DOF mismatch on convert#

Symptom: expected N joint DOFs … got M.

Fix: source CSV/PKL joint count must match the robot model. Check data/g1/README.md (or your extension) for joint order; use the correct --robot and --format.

Unknown task / robot#

Symptom: Unknown WBC task … or No WBC env builder for robot ….

Fix: use an id from wbc-mjlab-list-envs. Prefer --task Wbc-G1 over guessing --robot. Extension robots must call register_wbc_extension at import time.

CUDA / MuJoCo GL errors on train#

Symptom: EGL / GL import failures on headless machines.

Fix: set MUJOCO_GL=egl (or disable for non-rendering smoke tests). Training needs an NVIDIA GPU; for no-GPU try the live demo or Colab.

Install: Installation.

Resume loads the wrong run#

Symptom: training continues from an unexpected checkpoint.

Fix: pin the run and file:

uv run wbc-mjlab-train --task Wbc-G1 --dataset samples \
  --agent.resume True \
  --agent.load-run 2026-07-03_14-30-00 \
  --agent.load-checkpoint model_5000.pt

Details: Training.

Play has no checkpoint#

Symptom: play fails or uses a random/zero agent.

Fix: train once, or pass --checkpoint-file /path/to/model_*.pt. Default play picks the latest model_*.pt under logs/rsl_rl/<experiment>/.

Docs build / autodoc#

Local live reload: make docs-watch (watches docs/ and src/). One-shot: make docs. See docs/BUILDING.md.