isaac-sim-troubleshooting

Diagnose and resolve Isaac Sim 6 hangs, freezes, and performance issues on large USD scenes.

4.0k|530|Updated May 28, 2025
One-click install
npx skills add https://github.com/isaac-sim/IsaacSim --skill isaac-sim-troubleshooting
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: isaac-sim-troubleshooting
Source: https://github.com/isaac-sim/IsaacSim/tree/main/skills/isaac-sim-troubleshooting
Command: npx skills add https://github.com/isaac-sim/IsaacSim --skill isaac-sim-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Isaac Sim 6 (Kit 110) frequently hangs or freezes when working with large USD scenes (10K-150K+ prims) such as factory and warehouse digital twins, and finding the root cause across startup, stage loading, shader compilation, physics, rendering, and Nucleus networking is time-consuming without a structured reference.

Core Features & Use Cases

  • Guided Diagnosis Flowchart: Routes symptoms (startup hang, stage load stall, shader compile, physics freeze, Replicator hang, Hydra freeze, Nucleus timeout, OOM) to the correct remediation section.
  • Concrete Fixes with Commands: Provides ready-to-use launch flags, carb settings, and Python snippets for thread limiting, layer packaging, reference auditing, physics stabilization, and texture budget tuning.
  • Use Case: When Isaac Sim freezes while opening a warehouse-scale stage with thousands of layers, use this Skill to identify excessive layer count as the bottleneck and consolidate per-asset files into library layers, cutting load time from minutes to under a minute.

Quick Start

Ask the assistant to diagnose why Isaac Sim hangs when loading your large USD stage and apply the recommended fix from the troubleshooting reference.

Frequently Asked Questions about isaac-sim-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Isaac Sim hanging during stage loading?

Isaac Sim stage loading hangs are usually caused by excessive USD layer counts over 1,000 or missing external references. Audit layers with stage.GetUsedLayers() and consolidate per-asset files into a small number of library layers, which can reduce load time from minutes to under a minute.

Why does Isaac Sim freeze on startup?

Startup freezes commonly stem from extension conflicts, renderer initialization issues, thread over-subscription on high-core-count CPUs, or a Nucleus login popup. Try excluding problematic extensions, forcing Vulkan with --vulkan, resetting user settings, or limiting carb.tasking thread counts.

How long does Isaac Sim shader compilation take?

First-launch MDL shader compilation normally takes 5-15 minutes and is expected behavior. Subsequent launches reuse the shader cache stored in ~/.nvidia-omniverse/data/Kit/Isaac-Sim/shader_cache/, and deleting that folder forces a full rebuild.

Why does Replicator orchestrator.run() hang in Isaac Sim?

Replicator hangs when the timeline is not playing before orchestrator.run() is invoked, or when step_async() is called outside an async context. Start the timeline first and call app update once before frame capture so the renderer has a fresh frame.

Can I run Isaac Sim without Nucleus network access?

Yes, launch Isaac Sim with --/omni/client/enabled=false for local-only work to avoid Nucleus network hangs. You can also set /omni/client/timeout_seconds to 10.0 and copy needed USD assets to local disk.

How do I reduce GPU memory usage in large Isaac Sim scenes?

Enable UsdGeom.PointInstancer for repeated assets when prim counts exceed 150K, use texture atlases at reduced resolution, and lower the RTX texture streaming budget via /rtx/resourcemanager/textureMipCountBudget. Monitor usage with nvidia-smi.