voicebox/docs/content/docs/overview/troubleshooting.mdx

---
title: "Troubleshooting"
description: "Common issues and solutions for Voicebox"
---

This guide covers common issues you might encounter when using or developing Voicebox, along with solutions.

## Installation Issues

### macOS: "App is damaged and can't be opened"

This occurs because the app isn't signed with an Apple Developer certificate.

**Solution:**
```bash
# Remove the quarantine attribute
xattr -cr /Applications/Voicebox.app
```

### Windows: SmartScreen Warning

Windows SmartScreen may warn that the app is unrecognized.

**Solution:**
- Click "More info"
- Click "Run anyway"

<Callout type="info">
  This is expected for unsigned applications. We're working on code signing for future releases.
</Callout>

### Linux: AppImage Won't Run

**Solution:**
```bash
chmod +x voicebox-*.AppImage
./voicebox-*.AppImage
```

## Server Issues

### Backend Server Won't Start

**Symptoms:**
- Red status indicator in bottom-left corner
- "Failed to connect to server" error

**Solutions:**

<AccordionGroup>
  <Accordion title="Port Already in Use">
    Check if port 17493 is already in use:

    ```bash
    # macOS/Linux
    lsof -i :17493

    # Windows
    powershell -Command "Get-NetTCPConnection -LocalPort 17493 -State Listen"
    ```

    Kill the process using the port:
    ```bash
    # macOS/Linux
    kill -9 <PID>

    # Windows
    taskkill /PID <PID> /F
    ```
  </Accordion>

  <Accordion title="Permission Issues">
    The server binary might not have execute permissions:

    ```bash
    # macOS/Linux
    chmod +x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server
    ```
  </Accordion>

  <Accordion title="Check Logs">
    View server logs for errors:

    **macOS:**
    ```bash
    tail -f ~/Library/Application\ Support/sh.voicebox.app/logs/server.log
    ```

    **Windows:**
    ```bash
    type %APPDATA%\sh.voicebox.app\logs\server.log
    ```
  </Accordion>
</AccordionGroup>

### `flash-attn is not installed` Warning in Server Logs

**Symptoms:**
```
Warning: flash-attn is not installed. Will only run the manual PyTorch version.
Please install flash-attn for faster inference.
```

**This is harmless.** The warning is emitted by our transformer-based engines (Chatterbox / Qwen) on every startup. FlashAttention is an optional acceleration library — when it's not present, PyTorch's built-in scaled-dot-product attention (SDPA) runs instead, which is near-FA2 throughput on modern GPUs. Generation works normally.

**Why it shows up on every platform:**
- **Windows:** `flash-attn` has no official Windows support. The upstream project (Dao-AILab/flash-attention) still only says it *might* work, and source builds typically fail on recent CUDA/MSVC combinations.
- **macOS (Apple Silicon):** FlashAttention is CUDA-only and doesn't apply here at all. MLX has its own optimized attention kernels.
- **Linux:** It's not pinned in our requirements because installing it is fragile and version-sensitive; users who want it install it themselves.

**Solutions (all optional):**

<AccordionGroup>
  <Accordion title="Ignore it (recommended)">
    PyTorch SDPA is what actually runs the model, and on Ampere/Ada/Hopper GPUs it's within a few percent of FA2 for our workloads. You won't notice a meaningful speed difference.
  </Accordion>

  <Accordion title="Install flash-attn on Linux">
    ```bash
    pip install flash-attn --no-build-isolation
    ```

    Requires a matching CUDA toolkit. Build can take 20+ minutes.
  </Accordion>

  <Accordion title="Install flash-attn on Windows (community wheels)">
    Official builds don't exist, but community maintainers publish prebuilt wheels:

    - [kingbri1/flash-attention releases](https://github.com/kingbri1/flash-attention/releases)
    - [bdashore3/flash-attention releases](https://github.com/bdashore3/flash-attention/releases)

    Pick the wheel matching your exact CUDA + PyTorch + Python combination. Example:

    ```bash
    pip install https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu128torch2.8.0cxx11abiFALSE-cp312-cp312-win_amd64.whl
    ```

    Alternatively, run Voicebox's backend inside WSL2 and use the standard Linux wheels.
  </Accordion>
</AccordionGroup>

### Connection Timeout

**Symptoms:**
- Long loading times
- "Connection timeout" errors

**Solution:**
- Restart the app
- Check your firewall settings
- Ensure localhost is accessible

## Generation Issues

### First Generation is Very Slow

**Symptoms:**
- First generation takes 2-5 minutes
- Progress indicator stuck at "Loading model..."

**Explanation:**
This is expected behavior. The first generation downloads the selected TTS engine's model and initializes it. Sizes range from 350 MB (Kokoro) to 8 GB (TADA 3B).

**Solution:**
- Wait for the initial download to complete (progress is shown in Settings → Models)
- Subsequent generations reuse the cached model and are much faster
- Check your internet connection
- For low-bandwidth setups, start with Kokoro (~350 MB) or LuxTTS (~300 MB)

### Poor Voice Quality

**Symptoms:**
- Robotic or unnatural voice
- Missing emotion or prosody
- Pronunciation errors

**Solutions:**

<Steps>
  <Step title="Improve Voice Samples">
    - Use 10-30 seconds of clear audio
    - Avoid background noise
    - Ensure consistent speaking tone
    - Add multiple samples from the same speaker
  </Step>

  <Step title="Match Speaking Style">
    The generated voice will mimic the tone and style of your samples. If your sample is monotone, the generation will be too.
  </Step>

  <Step title="Adjust Text Formatting">
    - Use proper punctuation
    - Add commas for natural pauses
    - Capitalize proper nouns
  </Step>
</Steps>

### Generation Fails with "Out of Memory"

**Symptoms:**
- Generation crashes
- "CUDA out of memory" or "RuntimeError: out of memory"

**Solutions:**

<AccordionGroup>
  <Accordion title="Free GPU Memory">
    Close other GPU-intensive applications:
    - Games
    - Video editors
    - Multiple browser tabs with WebGL

    Then restart Voicebox.
  </Accordion>

  <Accordion title="Use CPU Mode">
    If your GPU doesn't have enough VRAM (need 6GB+), use CPU mode:

    Settings → Generation → Use CPU instead of GPU

    <Callout type="warn">
      CPU generation is 5-10x slower but uses system RAM instead of VRAM.
    </Callout>
  </Accordion>

  <Accordion title="Reduce Batch Size">
    For long text, split it into smaller chunks instead of generating all at once.
  </Accordion>
</AccordionGroup>

### MLX "Failed to load the default metallib" (Apple Silicon)

**Symptoms:**
- Generation fails with "library not found" or "metallib" errors
- Server logs reference missing Metal shader libraries

**Solutions:**

<AccordionGroup>
  <Accordion title="Rebuild the Server Binary">
    ```bash
    just build-server
    ```

    The build script bundles MLX Metal shader libraries on Apple Silicon automatically.
  </Accordion>

  <Accordion title="Reinstall MLX Dependencies">
    ```bash
    pip install -r backend/requirements-mlx.txt
    ```
  </Accordion>

  <Accordion title="Verify Backend Detection">
    Check Settings → Server Status. Should show **Backend: MLX** on Apple Silicon. If it shows **Backend: PYTORCH**, MLX isn't installed correctly.
  </Accordion>
</AccordionGroup>

## Audio Issues

### No Audio Playback

**Symptoms:**
- Generated audio won't play
- Playback button doesn't respond

**Solutions:**
- Check system audio settings
- Ensure audio output device is connected
- Try exporting and playing in a media player

### Crackling or Distorted Audio

**Symptoms:**
- Audio has static or distortion
- Clipping sounds

**Solutions:**
- Check if your input samples have distortion
- Reduce playback volume
- Re-generate with cleaner voice samples

## Development Issues

### Backend Won't Start in Dev Mode

**Symptoms:**
- `just dev-backend` or `just dev` fails
- Import errors or module not found

**Solutions:**

<AccordionGroup>
  <Accordion title="Python Version">
    Ensure Python 3.11 or higher:

    ```bash
    python --version
    ```

    If not, install Python 3.11+ and recreate the virtual environment.
  </Accordion>

  <Accordion title="Virtual Environment">
    Ensure venv is activated:

    ```bash
    # macOS/Linux
    source backend/venv/bin/activate

    # Windows
    backend\venv\Scripts\activate
    ```

    You should see `(venv)` in your prompt.
  </Accordion>

  <Accordion title="Dependencies">
    Reinstall dependencies — easiest via `just`:

    ```bash
    just setup
    ```

    Or manually:

    ```bash
    cd backend
    pip install -r requirements.txt
    pip install --no-deps chatterbox-tts
    pip install --no-deps hume-tada
    pip install git+https://github.com/QwenLM/Qwen3-TTS.git
    ```
  </Accordion>
</AccordionGroup>

### Tauri Build Fails

**Symptoms:**
- `bun run tauri build` fails
- Rust compilation errors

**Solutions:**

```bash
# Clean build artifacts
cd tauri/src-tauri
cargo clean

# Update Rust
rustup update

# Try building again
cd ../..
bun run tauri build
```

### OpenAPI Client Generation Fails

**Symptoms:**
- `./scripts/generate-api.sh` fails
- "Failed to fetch schema" error

**Solutions:**

<Steps>
  <Step title="Ensure Backend is Running">
    ```bash
    curl http://localhost:17493/openapi.json
    ```

    Should return JSON. If not, start the backend.
  </Step>

  <Step title="Check Port">
    Ensure nothing else is using port 17493
  </Step>

  <Step title="Regenerate Manually">
    ```bash
    cd backend
    source venv/bin/activate
    uvicorn main:app --reload --port 17493

    # In another terminal
    ./scripts/generate-api.sh
    ```
  </Step>
</Steps>

## Database Issues

### "Database is locked" Error

**Symptoms:**
- Profile or generation operations fail
- SQLite lock errors

**Solutions:**
- Close all Voicebox instances
- Delete the lock file:
  ```bash
  # macOS
  rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db-shm
  rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db-wal
  ```

### Corrupted Database

**Symptoms:**
- App crashes on launch
- Data missing or corrupted

**Solutions:**

<Callout type="warn">
  This will delete all your voice profiles and generation history. Export important profiles first if possible.
</Callout>

```bash
# macOS
rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db

# Windows
del %APPDATA%\sh.voicebox.app\data\voicebox.db
```

Restart the app to create a fresh database.

## Model Issues

### Model Download Fails

**Symptoms:**
- "Failed to download model" error
- Stuck at "Downloading..."

**Solutions:**
- Check your internet connection
- Check HuggingFace Hub status
- Try using a VPN if HuggingFace is blocked in your region
- Manually download via the HuggingFace CLI and place in the cache directory:

  ```bash
  pip install huggingface_hub
  huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base
  ```

### Qwen 0.6B Downloads the Same Files as 1.7B on Apple Silicon

**Symptoms:**
- You select Qwen 0.6B on an Apple Silicon Mac and the download is the same size as 1.7B
- Generation speed and VRAM usage match 1.7B, not the expected smaller model

**Explanation:**
This is intentional, not a bug. The MLX community only publishes `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16` — there is no 0.6B MLX build. Voicebox's model registry falls back to the 1.7B weights when 0.6B is selected on MLX (see `backend/backends/__init__.py`).

**Solution:**
- On Apple Silicon, both size options use the 1.7B model — pick either.
- If you specifically need a smaller model, switch to **Kokoro 82M** (~350 MB) or **LuxTTS** (~300 MB) — both CPU-realtime.
- On Windows/Linux with PyTorch, 0.6B and 1.7B are distinct repos and behave differently.

### Wrong Model Version

**Symptoms:**
- Generation quality suddenly degraded
- Different voice output

**Solutions:**
Clear the model cache and re-download. Replace the `Qwen*` glob with the engine org prefix for other engines (`ResembleAI*` for Chatterbox, `HumeAI*` for TADA, `hexgrad*` for Kokoro, etc.) or use `DELETE /models/{name}` via the API.

```bash
# macOS / Linux
rm -rf ~/.cache/huggingface/hub/models--Qwen*

# Windows
rmdir /s %USERPROFILE%\.cache\huggingface\hub\models--Qwen*
```

## Performance Issues

### Slow Generation on GPU

**Symptoms:**
- Generation slower than expected
- GPU not being utilized

**Solutions:**

<AccordionGroup>
  <Accordion title="Verify CUDA Installation">
    ```bash
    nvidia-smi
    ```

    Should show your GPU. If not, install CUDA drivers.
  </Accordion>

  <Accordion title="Check GPU Selection">
    If you have multiple GPUs, ensure Voicebox is using the right one.

    Settings → Generation → GPU Device
  </Accordion>

  <Accordion title="Update GPU Drivers">
    Outdated drivers can cause performance issues. Update to the latest NVIDIA drivers.
  </Accordion>

  <Accordion title="Apple Silicon: Confirm MLX Backend">
    Check Settings → Server Status. Should show **Backend: MLX** on Apple Silicon — MLX is 4–5× faster than PyTorch here. If it shows **Backend: PYTORCH**, reinstall MLX:

    ```bash
    pip install -r backend/requirements-mlx.txt
    ```

    GPU availability should read "Metal (Apple Silicon via MLX)".
  </Accordion>
</AccordionGroup>

### High Memory Usage

**Symptoms:**
- App uses excessive RAM
- System becomes sluggish

**Solutions:**
- Close unused voice profiles
- Clear generation history
- Restart the app periodically

## Update Issues

### "Update Check Failed"

**Solutions:**
- Confirm your internet connection — updates are fetched from GitHub releases.
- Ensure `github.com` is accessible and not blocked by a firewall or proxy.
- As a fallback, download the latest release from GitHub and install manually.

### "Invalid Signature" Error

**Solutions:**
- Re-download the installer — the signature may have been corrupted in transit.
- Verify the `.sig` file matches the installer; if it doesn't, file an issue.

## Remote Mode Issues

### Can't Connect to Remote Server

**Symptoms:**
- "Connection refused" error
- Remote server not found

**Solutions:**

<Steps>
  <Step title="Check Server Status">
    Ensure the remote server is running:

    ```bash
    curl http://<server-ip>:17493/health
    ```
  </Step>

  <Step title="Check Firewall">
    Ensure port 17493 is open on the remote server:

    ```bash
    # Allow port on Ubuntu/Debian
    sudo ufw allow 17493
    ```
  </Step>

  <Step title="Verify Network">
    - Ensure both machines are on the same network (for local servers)
    - Use IP address instead of hostname
    - Try pinging the server: `ping <server-ip>`
  </Step>
</Steps>

## Still Having Issues?

If you're still experiencing problems:

1. **Check GitHub Issues:** [github.com/jamiepine/voicebox/issues](https://github.com/jamiepine/voicebox/issues)
2. **Open a New Issue:** Provide:
   - Operating system and version
   - Voicebox version
   - Steps to reproduce
   - Error messages or logs
3. **Join Discord:** [discord.gg/voicebox](https://discord.gg/voicebox) (coming soon)

## Diagnostic Information

When reporting issues, include this information:

```bash
# Voicebox version
# Check Help → About in the app

# Operating system
uname -a  # macOS/Linux
systeminfo  # Windows

# Python version (for dev issues)
python --version

# GPU info (if generation issues)
nvidia-smi  # NVIDIA GPUs
```