cosmos3-env-troubleshoot

Cosmos3 Environment Troubleshooting

When to use this skill

• Use when a user hits an error during installation, environment setup, or first run
• Use when a traceback mentions torch, CUDA, missing modules, or shared libraries
• Use when Docker or container setup fails
• Use when checkpoint downloads fail or HuggingFace auth errors appear

Path convention

All paths below are relative to this file's location (.claude/skills/cosmos3-env-troubleshoot/).

Step 1: Match against known errors

Check the error message against the table below. Each row links to the canonical fix in the docs.

Step 2: If no documented fix matches, try common remediation

Run these diagnostic commands to collect information, then attempt fixes in order:

Diagnostic commands

# System
uname -a
cat /etc/os-release | head -5
 
# Python
python --version
which python

Remediation ladder (try in order)

1. Clear library path: export LD_LIBRARY_PATH=''

2. Reinstall venv: uv sync --all-extras --group=cu130-train --reinstall (or cu128-train on older drivers; drop -train only if you intentionally want the inference-only group)

3. Reinstall uv + venv from scratch:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv python install --reinstall
   rm -rf .venv
   uv sync --all-extras --group=cu130-train --reinstall
   source .venv/bin/activate

4. Check CUDA version alignment: the major CUDA version from nvidia-smi must match torch.version.cuda

5. Try Docker: if the host environment is too broken, fall back to the Docker container (see ../../../docs/setup.md)

Step 3: If still unresolved, generate a bug report

If none of the above resolves the issue, collect environment information and present the user with a pre-filled bug report they can submit as a GitHub issue.

Fill in the template below by running the diagnostic commands and inserting the results:

## Environment
 
- **OS**: <output of `uname -a`>
- **Python**: <output of `python --version`>
- **CUDA (system)**: <output of `nvidia-smi` — first line with driver/CUDA version>
- **CUDA (torch)**: <output of `python -c "import torch; print(torch.version.cuda)">`>
- **torch version**: <output of `python -c "import torch; print(torch.__version__)">`>
- **cosmos_framework version**: <output of `python -c "import cosmos_framework; print(cosmos_framework.__version__)"` or "not installed">
- **Installation method**: <uv sync / uv pip / Docker / NGC container>
 
## Error
 
```
<full traceback>
```
 
## What was tried
 
1. <list each remediation step attempted and its result>
 
## Additional context
 
<any other relevant details — multi-GPU setup, custom CUDA install, etc.>