# When Isaac Lab fails

Start below the policy: runtime, task registration, environment, training, then
artifact.

## Isaac Lab does not import or start

- Verify the Isaac Sim/Lab compatibility pair and how both were installed.
- On cloud hosts, prefer a matched prebuilt image before layering source
  installs into an unknown runtime.
- Confirm the Isaac Sim hardware and driver gate independently.

## The task cannot be found

- List the installed registry and compare the exact task entry point. Task IDs
  and script directories move across releases.
- In a pip-installed/prebuilt environment, make a custom task an external
  project that registers itself. Robium observed the internal-task route being
  disabled there because it is meant for upstream development.

## Training exits cleanly but the checkpoint seems missing

- Inspect the training library's experiment name and resolved configuration.
  Robium's Go2 RSL-RL run wrote under `unitree_go2_flat`, not the full task ID.
- Confirm save interval and output mount before rerunning paid compute.
- On the prebuilt image, a persistent volume mounted at `/workspace` can hide
  the bundled application. Robium used a non-overlapping path such as `/data`.

## Training is slow or unstable

- Reduce environments and iterations until resets and metrics are observable.
- Separate data loading, physics, rendering, and policy-update throughput.
- Run full training headless. Produce selected videos afterward rather than
  paying the rendering cost throughout training.
- Inspect the resolved reward configuration. In the verified Go2 task, costs
  were negative-weight reward terms and robot-specific configs overrode base
  weights through multiple layers.

## Playback or custom scripts fail

- Use the play script from the same library and release as the training run.
- A copied RSL-RL play script may import a sibling `cli_args` module; keep the
  script tree intact or provide the corresponding module path.
- Verify observation/action dimensions before assuming a checkpoint is portable
  across versions. Robium observed portability across one patch pair only.
- Interactive editor control and policy stepping can compete for the simulation
  timeline. Use headless execution and a view-only stream unless the combination
  is proven on the target release.

# Imitation learning and deployment

Use this card only when the task goes beyond the common RL train/play loop.
Isaac Lab's Mimic, teleoperation, robomimic scripts, exporters, and deployment
examples change quickly; the current official workflow is the source of truth.

## Imitation learning

- Start from an installed task that supports the selected teleoperation device
  and demonstration schema. Prove reset, task completion, and one replay before
  collecting volume.
- Keep the stages distinct: collect demonstrations, annotate or inspect success,
  generate augmented demonstrations with Mimic when appropriate, train through
  the supported imitation library, then evaluate named checkpoints.
- Generated demonstrations inherit the source task, scene, controller, and
  success predicate. Inspect their coverage and failures rather than treating a
  successful generation command as valid training data.
- The current official examples use Isaac Lab Mimic and robomimic, but script
  names, extras, tasks, and dataset formats are release-sensitive. Follow the
  [teleoperation and imitation guide](https://isaac-sim.github.io/IsaacLab/main/source/overview/imitation-learning/teleop_imitation.html)
  for the installed release.
- Cross into `data` for source-mix and demonstration-quality decisions. Cross
  into `lerobot` only when the artifact is a LeRobotDataset or the policy is
  trained through LeRobot.

## Export and deployment

- Playback is not deployment. First record the exact observation ordering,
  normalization, action scaling, recurrent state, control rate, and actuator
  limits that wrap the checkpoint.
- Prefer an exporter that preserves those semantics. Current Isaac Lab
  documentation includes LEAPP for supported manager-based RL workflows and
  policy-deployment examples; confirm the learning library, environment type,
  physics preset, and optional extras before choosing it.
- Re-run the policy in a second simulation or deployment harness before hardware
  when that can expose hidden simulator dependencies.
- Hardware rollout adds timing, estimator, actuator, network, and safety
  contracts. Begin with bounded commands and an independent stop path; do not
  infer safe behavior from the Isaac Lab playback video.
- Use the current [policy deployment guide](https://isaac-sim.github.io/IsaacLab/main/source/policy_deployment/index.html)
  and the selected robot/example repository for the actual export and hardware
  bridge. Do not generalize a HOVER, gear-insertion, ROS, or LEAPP recipe to an
  unrelated task.

## Evidence to keep

- Matched Isaac Lab/Isaac Sim release and physics preset.
- Dataset or reward configuration and task revision.
- Checkpoint plus preprocessing, postprocessing, and export metadata.
- Sim playback, cross-simulator result when used, control frequency, and the
  exact hardware safety envelope.

---
name: isaac-lab
description: Train, imitate, evaluate, and deploy robot policies with NVIDIA Isaac Lab.
---

# Isaac Lab

Isaac Lab adds a training loop to a matched Isaac Sim runtime. Prove a shipped
task end to end before creating a robot, environment, or reward.

## Establish the runtime

- Inherit the current hardware and operating-system gate from Isaac Sim.
- Verify the supported Isaac Sim and Isaac Lab pairing; newest plus newest is
  not automatically compatible.
- Prefer NVIDIA's matched Isaac Lab image on a cloud GPU. Use a source install
  when the workstation and version pairing are intentionally maintained.
- List registered tasks from the installed release instead of guessing a task
  ID or script path from an older tutorial.

## Prove the policy loop

- Choose the learning path explicitly: reinforcement learning from rewards, or
  imitation learning from demonstrations and generated variants.
- Run a known task headless with few environments and few iterations.
- Verify environment reset, observation/action shapes, reward terms, logging,
  and checkpoint creation before scaling parallel environments.
- Locate outputs using the training library's experiment name and current
  configuration, not an assumed task-name directory.
- Evaluate a named checkpoint through the matching play script. Export only
  after its observed behavior and metrics are useful.
- Add or change one reward, termination, terrain, or robot dimension at a time;
  a larger batch of edits hides which contract broke.

## Go deeper only when needed

- For NVIDIA's prebuilt image on RunPod, read
  [references/prebuilt-image-runpod.md](references/prebuilt-image-runpod.md)
  after the cloud provider is chosen.
- For the measured Unitree Go2 RSL-RL workflow, rewards, checkpoints, and custom
  task route, read [references/go2-rl-workflow.md](references/go2-rl-workflow.md).
- For teleoperation, Mimic/robomimic imitation learning, export, sim-to-sim, or
  hardware deployment, read
  [IMITATION-AND-DEPLOYMENT.md](IMITATION-AND-DEPLOYMENT.md).
- For runtime, output, task-registry, or interactive-viewer symptoms, start with
  [FAILURES.md](FAILURES.md).
- Use the current [Isaac Lab documentation](https://isaac-sim.github.io/IsaacLab/)
  and [source](https://github.com/isaac-sim/IsaacLab) for task IDs, script paths,
  configuration, and export behavior.
- Isaac Sim owns the underlying scene and sensors. LeRobot owns
  LeRobot-format dataset and real-robot training workflows; data owns the
  simulation-versus-real sourcing decision.

## Done

- A small shipped task trains, writes a discoverable checkpoint, plays back
  through the matching runtime, and provides a measured baseline for any custom
  task or scaled run.