OpenParable
Skip to content
← Back to skills

Isaac Sim Troubleshooting

Testing & Quality
isaac-sim-troubleshooting

Isaac Sim Troubleshooting is an Agent Skill for testing & quality published in the isaac-sim/IsaacSim repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Isaac Sim 6 (Kit 110) hang/freeze/perf reference for large USD scenes. Startup hangs, stage loading, MDL/shader compilation, physics stepping, Replicator, Hydra, Nucleus network, OOM crashes, perf tuning. Use when Isaac Sim hangs during stage load, shader compile, Nucleus fetch, physics, or Hydra render on factory/warehouse-scale stages.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/isaac-sim/IsaacSim/blob/HEAD/skills/isaac-sim-troubleshooting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/isaac-sim-troubleshooting, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Isaac Sim 6 Troubleshooting — Large USD Scene Hangs

Diagnosis and resolution for Isaac Sim 6.0 (Kit 110) hangs, freezes, and perf degradation on large USD scenes (10K-150K+ prims, factory/warehouse twins).

Upstream debugging docs: docs/isaacsim/utilities/debugging/ (profiling, Python debugging tutorials). Pair this skill with profile-isaac-sim for Tracy-based diagnosis.

Quick Diagnosis Flowchart

Isaac Sim hangs/freezes
    |
    +-- During startup (before stage load)?
    |       -> Section 1: Startup Hangs
    |
    +-- During stage open / USD loading?
    |       -> Section 2: Stage Loading Hangs
    |
    +-- During shader/material compilation?
    |       -> Section 3: MDL/Shader Compilation
    |
    +-- During physics stepping / `SimulationManager` setup or timeline play?
    |       -> Section 4: Physics Hangs
    |
    +-- During Replicator / sensor capture?
    |       -> Section 5: Replicator Hangs
    |
    +-- During rendering (viewport frozen)?
    |       -> Section 6: Hydra/Rendering Hangs
    |
    +-- Nucleus/remote asset fetch?
    |       -> Section 7: Nucleus Network Hangs
    |
    +-- OOM crash or memory spike?
    |       -> Section 8: Memory Issues
    |
    +-- Slow but not frozen?
            -> Section 9: Performance Optimization

Section 1: Startup Hangs

Common Causes and Fixes

1. Extension conflict (circular import)

./isaac-sim.sh --/app/extensions/exclude='["problematic.extension"]'

2. Renderer initialization freeze

./isaac-sim.sh --vulkan         # Force Vulkan
./isaac-sim.sh --reset-user     # Reset user settings

3. Thread over-subscription on high-core-count CPUs

./isaac-sim.sh \
    --/plugins/carb.tasking.plugin/threadCount=16 \
    --/plugins/omni.tbb.globalcontrol/maxThreadCount=16
simulation_app = SimulationApp({"headless": False, "limit_cpu_threads": 16})

4. Nucleus login popup hang — Force-kill Isaac Sim and restart. Complete login before proceeding.

Section 2: Stage Loading Hangs

Diagnosis

Check layer count:

for layer in stage.GetUsedLayers():
    print(f"  {layer.GetDisplayName()} ({layer.GetFileFormat().formatId})")

If layer count > 1,000, this is the primary bottleneck.

Common Causes

1. Excessive layer count (>1,000 layers)

StrategyCold LoadLayers
Per-asset files4 min11,488
Library packaging53s8

Fix: Package assets into library layers (consolidate per-asset files into a small number of library .usd/.usdc layers; see usd-composition-architecture for the layered-asset pattern).

2. Missing/broken references — Cause USD to try every resolver including network fallbacks. Fix: Audit references:

from pxr import Sdf
for layer in stage.GetUsedLayers():
    for ref in layer.GetExternalReferences():
        if not os.path.exists(ref):
            print(f"MISSING: {ref}")

Section 3: Shader/MDL Compilation

  • First launch always compiles MDL shaders — can take 5-15 minutes, normal
  • Subsequent launches use shader cache
  • Cache location: ~/.nvidia-omniverse/data/Kit/Isaac-Sim/shader_cache/
  • Force rebuild: delete cache folder

Section 4: Physics Hangs

Physics setup / first-play hangs (SimulationManager.setup_simulation, timeline.play(), or the legacy world.reset() flow — see Renaming Extensions to migrate off omni.isaac.core.World): usually caused by:

  • PhysicsScene not yet defined when physics starts.
  • Too many contact pairs on the first step.
  • GPU dynamics enabled with too many rigid bodies (>100K).

Fix:

# Ensure PhysicsScene exists before reset
if not stage.GetPrimAtPath("/World/PhysicsScene"):
    ps = UsdPhysics.Scene.Define(stage, "/World/PhysicsScene")

# Reduce initial contact storm
px_scene.CreateEnableStabilizationAttr().Set(True)

Section 5: Replicator Hangs

  • rep.orchestrator.run() hangs: ensure the timeline is playing (omni.timeline.get_timeline_interface().play() or isaacsim.core.experimental.utils.app.play(commit=True)) before invoking.
  • step_async() never completes: use await rep.orchestrator.step_async() correctly inside an async context.
  • Frame capture hangs: call app_utils.update_app() (or a simulation_app.update()) once before capture so the renderer has a fresh frame.

Section 6: Rendering (Hydra) Hangs

  • Viewport black and frozen: Check GPU memory (nvidia-smi)
  • RTX renderer OOM: Reduce texture streaming budget:
    carb.settings.get_settings().set("/rtx/resourcemanager/textureMipCountBudget", 256)
    

Section 7: Nucleus Network Hangs

  • Set timeout: carb.settings.set("/omni/client/timeout_seconds", 10.0)
  • Use local assets when possible: Copy needed USDs to local disk
  • Disable Nucleus: Launch with --/omni/client/enabled=false for local-only work

Section 8: Memory Issues

  • Prims > 150K: Enable instancing (UsdGeom.PointInstancer)
  • Textures: Use texture atlases, reduce resolution
  • Monitor: watch -n1 'nvidia-smi --query-gpu=memory.used,memory.free --format=csv'

Section 9: Performance Optimization

  • Layer count: Package into library layers (see Section 2)
  • Mesh instancing: Use PointInstancer for repeated assets
  • Payload loading: Mark large sub-scenes as unloaded payloads
  • Physics: Reduce collision mesh complexity for non-critical objects