voicebox/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"

<Note>
  This is expected for unsigned applications. We're working on code signing for future releases.
</Note>

## 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
    netstat -ano | findstr :17493
    ```

    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/com.voicebox.app/backend/voicebox-server
    ```
  </Accordion>

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

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

    **Windows:**
    ```bash
    type %APPDATA%\com.voicebox.app\logs\server.log
    ```
  </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 Qwen3-TTS model (~2-4GB) and initializes it.

**Solution:**
- Wait for the initial download to complete
- Subsequent generations will be much faster
- Check your internet connection

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

    <Warning>
      CPU generation is 5-10x slower but uses system RAM instead of VRAM.
    </Warning>
  </Accordion>

  <Accordion title="Reduce Batch Size">
    For long text, split it into smaller chunks instead of generating all at once.
  </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:**
- `bun run dev:server` 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:

    ```bash
    cd backend
    pip install -r requirements.txt
    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/com.voicebox.app/data/voicebox.db-shm
  rm ~/Library/Application\ Support/com.voicebox.app/data/voicebox.db-wal
  ```

### Corrupted Database

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

**Solutions:**

<Warning>
  This will delete all your voice profiles and generation history. Export important profiles first if possible.
</Warning>

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

# Windows
del %APPDATA%\com.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 and place in cache directory

### Wrong Model Version

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

**Solutions:**
Clear the model cache and re-download:

```bash
# macOS
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>
</AccordionGroup>

### High Memory Usage

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

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

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

For more detailed troubleshooting, see the [TROUBLESHOOTING.md](https://github.com/jamiepine/voicebox/blob/main/docs/TROUBLESHOOTING.md) file in the repository.