Installation Issues

RoboDojo depends on Isaac Sim, Isaac Lab, CUDA-capable NVIDIA drivers, local assets, and policy-side Python environments. When installation fails, first separate the problem into system compatibility, Python/package setup, asset download, or Docker/container setup.

Hardware or driver does not meet Isaac Sim requirements

Symptoms: Isaac Sim fails to launch, crashes during startup, cannot create a rendering context, or exits before RoboDojo evaluation begins.

Cause: The GPU, driver, RAM, VRAM, or OS may not satisfy Isaac Sim’s requirements. Isaac Sim 5.1 documents Ubuntu 22.04/24.04 support, 32 GB RAM minimum, 16 GB VRAM minimum, and tested Linux driver versions in the 580 series. It also notes that GPUs without RT cores are not supported.

What to try:

1. Check the host:

   nvidia-smi
   lsb_release -a
   free -h

2. Compare the machine against the Isaac Sim 5.1 requirements.

3. Run RoboDojo’s install verification:

   bash scripts/robodojo.sh doctor --env-cfg arx_x5

4. If the driver is too old or the GPU has no RT cores, fix that before reinstalling RoboDojo packages.

Isaac Sim compatibility checker fails

Symptoms: The Isaac Sim compatibility check reports missing requirements or the machine looks valid but Isaac Sim still fails early.

Cause: Isaac Sim provides a lightweight compatibility checker specifically for verifying system requirements. A failed check usually means the problem is below RoboDojo, such as GPU, driver, OS, or rendering support.

What to try:

1. Run the compatibility check from the Isaac Sim installation when available. In the container workflow, Isaac Sim documents:

   ./isaac-sim.compatibility_check.sh --/app/quitAfter=10 --no-window

2. Fix the reported system issue, then rerun bash scripts/robodojo.sh doctor --env-cfg arx_x5.

Official reference: Isaac Sim requirements and Isaac Sim container installation.

First Isaac Sim launch takes a long time

Symptoms: The first time Isaac Sim or a RoboDojo evaluation starts, the process appears to hang for a long time before the simulator window or headless run becomes active.

Cause: On first launch, Isaac Sim compiles shaders, builds caches, initializes extensions, and prepares local runtime data. This can take much longer than later launches, especially on a fresh machine, fresh Docker image, or empty Omniverse cache directory.

What to try:

• Wait for the first launch to finish instead of interrupting it immediately.
• Watch CPU/GPU/disk activity to confirm the process is still working.
• Keep Isaac Sim and Omniverse cache directories persistent between runs, especially in Docker.
• After the first successful launch, later starts should usually be faster.

Later Isaac Sim launches still take a long time

Symptoms: Isaac Sim has already launched successfully before, but later starts still pause for a long time while loading a scene or starting evaluation.

Cause: Isaac Sim or RoboDojo may be trying to fetch material assets, textures, or other referenced online resources. This is more likely on machines with restricted internet access, unstable DNS, proxy issues, or blocked NVIDIA / Omniverse asset endpoints.

What to try:

• Check that the machine has working network access before launching evaluation.
• If the machine is behind a proxy or firewall, make sure Isaac Sim can reach the required asset endpoints.
• Finish RoboDojo asset download with bash scripts/init_assets.sh before evaluation.
• If running in Docker, keep cache mounts persistent so successfully fetched assets are reused.
• If the process eventually prints a missing material or asset URL, use that path to identify the blocked resource.

Python or GLIBC mismatch during Isaac Sim package install

Symptoms: Isaac Sim Python packages cannot be found, pip reports no matching distribution, or package import fails immediately after install.

Cause: Isaac Sim’s Python package installation has strict platform requirements. The official Python install docs say Isaac Sim requires Python 3.11, and Linux package discovery requires GLIBC 2.35 or newer.

What to try:

1. Use RoboDojo’s install script instead of mixing Python environments manually:

   bash scripts/install.sh

2. Confirm the active Python environment:

   python --version
   ldd --version

3. If you are on an older Linux distribution, use the Docker path or move to a host compatible with Isaac Sim’s Python package requirements.

Official reference: Isaac Sim Python Environment Installation.

Assets are missing or paths point to the wrong location

Symptoms: RoboDojo starts but fails to load USD files, robot assets, object assets, materials, or evaluation layouts.

Cause: RoboDojo assets are not installed, or robot embodiment paths still point to a previous checkout. Isaac Sim also notes that an internet connection is required for online Isaac Sim assets and some extensions.

What to try:

1. Download RoboDojo assets:

   bash scripts/init_assets.sh

2. Update local embodiment paths:

   python utils/update_embodiment_config_path.py

3. Check the required asset directories:

   Assets/Robots
   Assets/Object/RoboDojo
   Assets/Eval_Layout/RoboDojo
   Assets/Material

4. Check the expected evaluation layout directory exists:

   Assets/Eval_Layout/RoboDojo/arx_x5/0

5. Run a lightweight asset/path check:

   bash scripts/robodojo.sh doctor --skip-isaac --skip-conda --skip-policy

6. If the machine is offline or behind a restricted network, finish all asset downloads before evaluation.

Official reference: Isaac Sim requirements. RoboDojo setup reference: Install & Download.

Isaac Sim or Isaac Lab imports fail

Symptoms: The install finishes, but evaluation fails immediately with Python import errors for isaacsim, isaaclab, or related simulator packages.

Cause: The simulator environment is incomplete, the wrong Conda environment is active, or the Isaac Sim / Isaac Lab install step was interrupted.

What to try:

1. Activate the RoboDojo environment and test imports:

   conda activate RoboDojo
   python - <<'PY'
   import isaacsim
   import isaaclab
   print("Isaac imports ok")
   PY

2. Resume installation from the failed layer:

   bash scripts/install.sh --from isaacsim
   bash scripts/install.sh --from isaaclab

3. If you are not sure where the install failed, resume from one of the supported steps:

   bash scripts/install.sh --from <step>

   Supported steps include system, conda, base_deps, submodules, isaacsim, isaaclab, and curobo.

Docker container cannot see the GPU

Symptoms: Docker starts but Isaac Sim reports no GPU, CUDA is unavailable, or rendering fails inside the container.

Cause: Docker is not running with NVIDIA GPU access, the NVIDIA Container Toolkit is missing, or runtime flags are incomplete. Isaac Sim’s container docs use --gpus all, require the EULA environment variable, and suggest --runtime=nvidia if GPU detection has issues.

What to try:

1. Verify Docker GPU access:

   docker run --rm --gpus all nvidia/cuda:12.8.1-cudnn-devel-ubuntu22.04 nvidia-smi

2. Install or repair Docker NVIDIA support:

   sudo bash docker/install_docker_nvidia.sh

3. Rebuild and rerun the RoboDojo Docker image:

   docker compose up -d --build

Official reference: Isaac Sim container installation. RoboDojo Docker reference: Optional: Install with Docker.

Docker networking or cache problems

Symptoms: The simulator container cannot connect to the policy server, first launch is very slow every time, or logs are hard to find after a crash.

Cause: Docker bridge networking can hide the host network interface from the simulator, and missing cache/log mounts force Isaac Sim to rebuild caches repeatedly. Isaac Sim’s container docs recommend host networking for livestreaming and document cache, log, config, data, and package mounts for persistent state.

What to try:

1. For RoboDojo Docker evaluation, prefer host networking:

   docker run --rm -it --gpus all --network host --ipc host ...

2. Keep the cache mounts from Optional: Install with Docker so Warp and Omniverse caches persist between runs.

3. If connecting to a host-side policy server from a container, use --network host with --policy-host 127.0.0.1, or use a reachable host/IP according to your Docker network mode.

4. Inspect container logs with:

   docker ps
   docker logs <container_id_or_name>

   For RoboDojo simulator containers, inspect the command’s terminal output and mounted Omniverse cache/log directories.

Official reference: Isaac Sim container installation and Isaac Sim setup tips.

Related page: Evaluation Issues.