isaac-sim-troubleshooting

Isaac Sim のトラブルシューティング

目的

Isaac Sim の起動時のハング、ステージ読み込みの停滞、MDL／シェーダーのコンパイル停止、物理演算のステップ処理のブロック、Replicator／Hydra の問題、Nucleus の遅延、GPU OOM によるクラッシュを診断します。

前提条件

• ライブラリの障害を調べるには、設定済みのビルド環境またはインストール済みパッケージ環境が必要です。
• Kit／GPU の前提条件は、診断対象の Kit ワークロードにのみ適用されます。

制限事項

• 症状の一覧は経験則に基づくものであり、根本原因が複数のサブシステムにまたがる場合があります。
• 修正によっては、ローカルの Kit ビルドまたは NVIDIA 内部専用パッケージが必要です。

トラブルシューティング

エラー／症状	原因	解決方法
拡張機能またはインポートが見つからない	$ISAAC_SIM_DIR が誤っている、またはビルドが古い	環境変数を _build/linux-x86_64/release に設定するか、再ビルドします
フレームが黒い、または空になる	ライトがない、または非 RTX レンダリングモードになっている	ドームライト／キーライトを追加し、RTX／PathTracing の設定を確認します
ステージ読み込み時または初回レンダリング時にハングする	MDL のコンパイル、またはステージが大きすぎる	isaac-sim-troubleshooting の切り分け手順に従います
終了時または SimulationApp.close() でハングする	shutdown_and_release_framework() 中に carb.tasking のスレッドプールでデッドロックが発生する	SIGALRM ウォッチドッグを使用します（セクション 1a を参照）。デッドロック中の C 拡張機能が GIL を保持していると、threading.Event は発火できません

大規模な USD シーン（10K～150K 以上のプリム、工場／倉庫のデジタルツイン）で発生する Isaac Sim 6.0（Kit 110）のハング、フリーズ、パフォーマンス低下の診断と解決方法です。

上流のデバッグドキュメント：docs/isaacsim/utilities/debugging/（プロファイリング、Python デバッグのチュートリアル）。Tracy ベースの診断には、このスキルと profile-isaac-sim を併用してください。

スタンドアロンライブラリの診断

Kit を使用せず、通常のプロセスで再現します。インストール済みのディストリビューション、 wheel／ネイティブ依存関係、ローダーパス、再配置を調べます。ライブラリの診断には isaacsim.common.logging.Logger、Kit には carb.log_* を使用し、print() は意図的な標準出力の結果にのみ使用します。

クイック診断フローチャート

Isaac Sim hangs/freezes
    |
    +-- During startup (before stage load)?
    |       -> Section 1: Startup Hangs
    |
    +-- During shutdown / SimulationApp.close()?
    |       -> Section 1a: Shutdown Hangs (Kit Framework Deadlock)
    |
    +-- 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

セクション 1：起動時のハング

一般的な原因と修正方法

1. 拡張機能の競合（循環インポート）

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

2. レンダラーの初期化時のフリーズ

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

3. コア数の多い CPU でのスレッドの過剰なオーバーサブスクリプション

./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 のログインポップアップでハングする — Isaac Sim を強制終了して再起動します。続行する前にログインを完了してください。

セクション 1a：終了時のハング（Kit フレームワークのデッドロック）

症状

SimulationApp.close() が返ってきません。プロセスが無期限にハングします（または CI が 1500s で強制終了するまでハングします）。スタックトレースでは、shutdown_and_release_framework() または unload_all_plugins() 中の carb.tasking スレッドプールの終了処理において、スレッドが futex_wait でブロックされています。

根本原因

shutdown_and_release_framework() は app->shutdown() を呼び出した後、framework->unloadAllPlugins() を呼び出します。これらは、ネイティブスレッドの結合処理で内部的にデッドロックする間、GIL を保持する C 拡張機能の呼び出しです。Python 側の threading.Event.wait() ウォッチドッグは、タイムアウトを確認して os.kill() を呼び出すのに GIL が必要なため、発火できず、飢餓状態になります。

修正方法：SIGALRM ウォッチドッグ

SIGALRM は GIL の状態にかかわらず、カーネルから配信されます。ブロッキングする C 呼び出しの前にアラームを設定し、デッドロックした場合はアラームハンドラーで無条件にプロセスを SIGKILL します。

パターン（一般化したもの。デッドロックする可能性のあるネイティブ終了処理に適用してください）：

1. 以前の SIGALRM ハンドラーを保存します。
2. os.kill(os.getpid(), signal.SIGKILL) を呼び出すハンドラーを設定します。
3. signal.alarm(timeout_seconds) を設定します。完全なシャットダウンには 120s、プラグインのアンロードには 30s を指定します。
4. ブロッキングするネイティブ関数を呼び出します。
5. finally 内で、アラームをキャンセルし（signal.alarm(0)）、以前のハンドラーを復元します。

この問題を疑うべき状況

• すべてのテストアサーションに合格した後、CI ジョブがハングする（シャットダウン段階）。
• strace で、メインスレッドが Kit のプラグインシステム内の futex_wait で停止していることが確認できる。
• Python ベースのタイムアウト機構（threading、asyncio）が、発火しないまま失敗する。

重要なポイント

Python のウォッチドッグが、GIL を無期限に保持する可能性のある C 拡張の呼び出しを監視する場合、threading.Event／threading.Timer は処理を妨げられます。CPython で GIL に依存しないタイムアウトを確実に実現できる方法は、signal.alarm()（Linux）または os.alarm() のみです。

参考資料

• ファイル：source/extensions/isaacsim.simulation_app/isaacsim/simulation_app/simulation_app.py

セクション 2：ステージの読み込みがハングする

診断

レイヤー数を確認します：

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

レイヤー数が 1,000 を超えている場合、これが主なボトルネックです。

よくある原因

1. レイヤー数が多すぎる（1,000 レイヤー超）

方針	初回読み込み	レイヤー数
アセットごとのファイル	4 分	11,488
ライブラリへのパッケージ化	53 秒	8

解決方法：アセットをライブラリレイヤーにパッケージ化します（アセットごとのファイルを少数のライブラリ .usd／.usdc レイヤーに統合します。レイヤー化されたアセットのパターンについては usd-composition-architecture を参照してください）。

2. 参照の欠落／破損 — USD がネットワークへのフォールバックを含むすべてのリゾルバーを試行する原因になります。解決方法：参照を監査します：

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

セクション 3：シェーダー／MDL のコンパイル

• 初回起動時は必ず MDL シェーダーがコンパイルされます。5～15 分かかることがありますが、正常です。
• 2 回目以降の起動ではシェーダーキャッシュが使用されます。
• キャッシュの場所：~/.nvidia-omniverse/data/Kit/Isaac-Sim/shader_cache/
• 強制的に再構築するには、キャッシュフォルダーを削除します。

セクション 4：物理演算のハング

物理演算のセットアップ／初回再生時のハング（SimulationManager.setup_simulation、timeline.play()、または旧式の world.reset() フロー。omni.isaac.core.World から移行するには、拡張機能の名称変更を参照してください）：通常、次の原因で発生します。

• 物理演算の開始時点で PhysicsScene がまだ定義されていない。
• 最初のステップで接触ペアが多すぎる。
• 剛体が多すぎる状態（100K 超）で GPU ダイナミクスが有効になっている。

解決方法：

# 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)

セクション 5：Replicator のハング

• rep.orchestrator.run() がハングする：呼び出す前にタイムラインが再生中であることを確認します（omni.timeline.get_timeline_interface().play() または isaacsim.core.experimental.utils.app.play(commit=True)）。
• step_async() が完了しない：非同期コンテキスト内で await rep.orchestrator.step_async() を正しく使用します。
• フレームのキャプチャがハングする：キャプチャの前に app_utils.update_app()（または simulation_app.update()）を 1 回呼び出し、レンダラーに最新のフレームを用意します。

セクション 6：レンダリング（Hydra）のハング

• ビューポートが黒くなり、フリーズする：GPU メモリを確認します（nvidia-smi）。
• RTX レンダラーの OOM：テクスチャストリーミングの予算を減らします：

  carb.settings.get_settings().set("/rtx/resourcemanager/textureMipCountBudget", 256)
  

セクション 7：Nucleus ネットワークのハング

• タイムアウトを設定します：carb.settings.set("/omni/client/timeout_seconds", 10.0)
• 可能な場合はローカルアセットを使用します：必要な USD をローカルディスクにコピーします。
• Nucleus を無効にします：ローカルのみで作業する場合は --/omni/client/enabled=false を指定して起動します。

セクション 8：メモリの問題

• Prim が 150K を超える場合：インスタンス化を有効にします（UsdGeom.PointInstancer）。
• テクスチャ：テクスチャアトラスを使用し、解像度を下げます。
• 監視：watch -n1 'nvidia-smi --query-gpu=memory.used,memory.free --format=csv'

セクション 9：パフォーマンスの最適化

• レイヤー数：ライブラリレイヤーにパッケージ化します（セクション 2 を参照）。
• メッシュのインスタンス化：繰り返し使用するアセットには PointInstancer を使用します。
• ペイロードの読み込み：大規模なサブシーンを未読み込みのペイロードとして指定します。
• 物理演算：重要度の低いオブジェクトでは、衝突メッシュの複雑さを抑えます。