Skip to content

troubleshooting.md

Latest commit

 

History

History
144 lines (103 loc) · 3.82 KB

troubleshooting.md

File metadata and controls

144 lines (103 loc) · 3.82 KB

Windows Troubleshooting

Common issues and fixes specific to running Stable Audio 3 on Windows.

torchaudio: "Couldn't find appropriate backend"

Symptom:

RuntimeError: Couldn't find appropriate backend to handle uri output.wav and format None.

Cause: torchaudio has no audio I/O backend installed. On Linux, sox is typically available. On Windows, nothing ships by default.

Fix:

uv pip install soundfile

PyTorch installed without CUDA

Symptom:

>>> torch.cuda.is_available()
False
>>> torch.__version__
'2.7.1+cpu'

Cause: The project's pyproject.toml only configures the PyTorch CUDA index for Linux (sys_platform == 'linux').

Fix:

uv pip install torch==2.7.1+cu128 torchaudio==2.7.1+cu128 --index-url https://download.pytorch.org/whl/cu128 --reinstall

Flash Attention won't install / build fails

Symptom: pip install flash-attn fails with C++ compilation errors or missing MSVC/CUDA toolkit.

Cause: flash-attn has no official Windows wheels. Building from source requires Visual Studio Build Tools with MSVC and the matching CUDA toolkit.

Fix: Use pre-built wheels. Match your Python version:

Python Wheel
3.10 flash_attn-2.8.3+cu128torch2.7.0cxx11abiFALSE-cp310-cp310-win_amd64.whl
3.11 flash_attn-2.8.3+cu128torch2.7.0cxx11abiFALSE-cp311-cp311-win_amd64.whl
3.12 flash_attn-2.8.3+cu128torch2.7.0cxx11abiFALSE-cp312-cp312-win_amd64.whl
3.13 flash_attn-2.8.3+cu128torch2.7.0cxx11abiFALSE-cp313-cp313-win_amd64.whl

Download from: https://github.com/kingbri1/flash-attention/releases/tag/v2.8.3

uv pip install https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu128torch2.7.0cxx11abiFALSE-cp310-cp310-win_amd64.whl

Important: Your PyTorch CUDA version must match the wheel. These wheels require cu128, so use torch==2.7.1+cu128.

HF download hangs / lock file errors

Symptom:

Still waiting to acquire lock on ...\.cache\huggingface\hub\.locks\models--stabilityai--stable-audio-3-medium\....lock

Cause: A previous download process crashed or was killed, leaving stale lock files. Or multiple download processes are running simultaneously.

Fix:

  1. Kill all Python processes: 
    Get-Process python* | Stop-Process -Force
  2. Delete the lock directory: 
    Remove-Item "$env:USERPROFILE\.cache\huggingface\hub\.locks\models--stabilityai--stable-audio-3-medium" -Recurse -Force
  3. Retry the download (single process only).

winget not found in PowerShell

Symptom:

winget: The term 'winget' is not recognized

Cause: winget is installed but not on PATH in your current shell session (common in VS Code terminals, SSH sessions, etc.).

Fix: Use the full path:

& "$env:LOCALAPPDATA\Microsoft\WindowsApps\winget.exe" install git-xet

git clone of HF repo fails with "Password authentication not supported"

Symptom:

remote: Password authentication in git is no longer supported.
fatal: Authentication failed

Fix: Use your HF token as the password. Your token is stored at %USERPROFILE%\.cache\huggingface\token.

Option 1 — Use hf download instead (recommended):

hf download stabilityai/stable-audio-3-medium

Option 2 — Clone with token in URL:

git clone https://YOUR_USERNAME:YOUR_HF_TOKEN@huggingface.co/stabilityai/stable-audio-3-medium

Output audio is static / glitchy (Medium model)

Cause: Flash Attention not installed or not working correctly.

Verify:

.\.venv\Scripts\python.exe -c "import flash_attn; from flash_attn import flash_attn_func; print('OK:', flash_attn.__version__)"

If this errors, reinstall flash-attn (see above).