Troubleshooting

Solutions to common issues with Izwi.

Installation Issues

macOS: “Izwi can’t be opened because it is from an unidentified developer”

The app isn’t code-signed yet:

Go to System Settings → Privacy & Security
Scroll down to find the Izwi message
Click Open Anyway

macOS: Command not found: izwi

The CLI tools aren’t in your PATH:

# Add to ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload
source ~/.zshrc

Linux: Permission denied installing .deb

Use sudo:

sudo dpkg -i izwi_*.deb

Windows: SmartScreen blocks installation

Click More info
Click Run anyway

Server Issues

Server won’t start

Check if port is in use:

lsof -i :8080

Use a different port:

izwi serve --port 9000

Check for existing Izwi processes:

pkill -f izwi
izwi serve

Can’t connect to server

Verify server is running:
izwi status

Check the operational probes:

curl -f http://localhost:8080/livez
curl -f http://localhost:8080/readyz

Check the correct URL:
http://localhost:8080
Check firewall settings

Server crashes on startup

Check logs:

izwi serve --log-level debug

Common causes:

Insufficient memory
Corrupted model files
Missing dependencies

Model Issues

Model download fails

Network issues:

Check internet connection
Try again (downloads resume automatically)
Use a VPN if region-blocked

Disk space:

df -h

Ensure you have enough free space (models can be 1-10+ GB). Corrupted download:

izwi rm <model-name>
izwi pull <model-name>

Model won’t load

Insufficient memory: Check available RAM:

# macOS/Linux
free -h

# Or check Activity Monitor / Task Manager

Try a smaller model or close other applications. Corrupted model:

izwi rm <model-name>
izwi pull <model-name>

Model not detected after manual download

Verify correct directory:
- macOS: ~/Library/Application Support/izwi/models/
- Linux: ~/.local/share/izwi/models/
- Windows: %APPDATA%\izwi\models\
Check folder name matches expected variant name
Restart the server:
izwi serve

Performance Issues

Inference is slow

Use GPU acceleration: macOS (Metal):

izwi serve --backend metal

Linux (Docker CUDA):

CUDA_COMPUTE_CAP=80 docker compose --profile cuda up

Linux/Windows source build (CUDA):

# Linux source install
IZWI_BUILD_BACKEND=cuda ./scripts/install-cli.sh

# Windows package-scoped builds
cargo build --release -p izwi-cli --features cuda
cargo build --release -p izwi-server --features cuda

For Whisper CUDA performance experiments, add Candle-backed feature flags only on hosts with the matching NVIDIA libraries, for example --features cuda,flash-attn or --features cuda,cudnn. Use smaller models:

Qwen3-TTS-12Hz-0.6B-Base instead of Qwen3-TTS-12Hz-1.7B-Base
Quantized variants (-4bit)

Close other applications to free memory

High memory usage

Unload unused models:

izwi models unload <model-name>

Use quantized models for lower memory footprint

Audio generation stutters

Ensure models are fully loaded before use
Use streaming mode for long text
Check system resources

Audio Issues

No audio output

Check system audio:

Verify speakers/headphones are connected
Check system volume
Test with another application

Check audio file:

# Play with system player
afplay output.wav  # macOS
aplay output.wav   # Linux

Poor transcription quality

Improve audio quality:

Use a better microphone
Reduce background noise
Speak clearly

Use a larger model:

izwi pull Qwen3-ASR-1.7B-GGUF
izwi transcribe audio.wav --model Qwen3-ASR-1.7B-GGUF

Specify language:

izwi transcribe audio.wav --language en

Microphone not detected (Web UI)

Check browser permissions for microphone access
Ensure correct input device is selected in system settings
Try a different browser

GPU Issues

Metal not working (macOS)

Verify Apple Silicon:

uname -m  # Should show "arm64"

Check macOS version:

sw_vers  # Should be 12.0+

Enable Metal:

izwi serve --backend metal

CUDA not detected (Linux/Windows)

Check NVIDIA drivers:

nvidia-smi

For Docker CUDA on Linux, verify the NVIDIA driver and container runtime. For source builds, verify CUDA Toolkit installation:

nvcc --version

If you installed from source, rebuild with CUDA support:

# Linux source install
IZWI_BUILD_BACKEND=cuda ./scripts/install-cli.sh

# Windows package-scoped builds
cargo build --release -p izwi-cli --features cuda
cargo build --release -p izwi-server --features cuda

Verify runtime backend state:

izwi serve --backend cuda
izwi status --detailed

Web UI Issues

UI won’t load

Verify server is running:
izwi status
Check the URL: http://localhost:8080
Clear browser cache
Try incognito/private mode

UI shows “No models loaded”

Download a model:
izwi pull Qwen3-TTS-12Hz-0.6B-Base

Load the model:

izwi models load Qwen3-TTS-12Hz-0.6B-Base

Refresh the page

Features not working

Ensure required models are loaded:

Feature	Required Model Type
TTS	`-tts-`
Transcription	`Parakeet-`, `Whisper-`, `Qwen3-ASR-`, `Granite-Speech-`, or `LFM2.5-Audio-*`
Chat	`Qwen3-`, `Qwen3.5-`, `LFM2.5-1.2B-*`, or `Gemma-3-1b-it`
Voice Cloning	`Qwen3-TTS-12Hz--Base`
Voice Design	`Qwen3-TTS-12Hz-1.7B-VoiceDesign*`

API Issues

401 Unauthorized

Izwi doesn’t require authentication by default. If you’re getting this error:

Check you’re connecting to the right server
Verify no proxy is interfering

404 Not Found

Check the endpoint URL:

TTS: POST /v1/audio/speech
Transcription: POST /v1/audio/transcriptions
Chat: POST /v1/chat/completions

For the full route list, including preview first-party APIs, admin routes, and realtime WebSockets, see the API Reference.

500 Internal Server Error

Check server logs:

izwi serve --log-level debug

Common causes:

Model not loaded
Invalid request format
Insufficient memory

Getting More Help

Collect diagnostic information

izwi version --full
izwi status --detailed

Check logs

izwi serve --log-level debug

Report issues

Open an issue on GitHub with:

Izwi version (izwi version --full)
Operating system and version
Steps to reproduce
Error messages and logs

GitHub Issues

Home

Reference & Help

Troubleshooting

Installation Issues

macOS: “Izwi can’t be opened because it is from an unidentified developer”

macOS: Command not found: izwi

Linux: Permission denied installing .deb

Windows: SmartScreen blocks installation

Server Issues

Server won’t start

Can’t connect to server

Server crashes on startup

Model Issues

Model download fails

Model won’t load

Model not detected after manual download

Performance Issues

Inference is slow

High memory usage

Audio generation stutters

Audio Issues

No audio output

Poor transcription quality

Microphone not detected (Web UI)

GPU Issues

Metal not working (macOS)

CUDA not detected (Linux/Windows)

Web UI Issues

UI won’t load

UI shows “No models loaded”

Features not working

API Issues

401 Unauthorized

404 Not Found

500 Internal Server Error

Getting More Help

Collect diagnostic information

Check logs

Report issues

See Also

​Installation Issues

​macOS: “Izwi can’t be opened because it is from an unidentified developer”

​macOS: Command not found: izwi

​Linux: Permission denied installing .deb

​Windows: SmartScreen blocks installation

​Server Issues

​Server won’t start

​Can’t connect to server

​Server crashes on startup

​Model Issues

​Model download fails

​Model won’t load

​Model not detected after manual download

​Performance Issues

​Inference is slow

​High memory usage

​Audio generation stutters

​Audio Issues

​No audio output

​Poor transcription quality

​Microphone not detected (Web UI)

​GPU Issues

​Metal not working (macOS)

​CUDA not detected (Linux/Windows)

​Web UI Issues

​UI won’t load

​UI shows “No models loaded”

​Features not working

​API Issues

​401 Unauthorized

​404 Not Found

​500 Internal Server Error

​Getting More Help

​Collect diagnostic information

​Check logs

​Report issues

​See Also

Installation Issues

macOS: “Izwi can’t be opened because it is from an unidentified developer”

macOS: Command not found: izwi

Linux: Permission denied installing .deb

Windows: SmartScreen blocks installation

Server Issues

Server won’t start

Can’t connect to server

Server crashes on startup

Model Issues

Model download fails

Model won’t load

Model not detected after manual download

Performance Issues

Inference is slow

High memory usage

Audio generation stutters

Audio Issues

No audio output

Poor transcription quality

Microphone not detected (Web UI)

GPU Issues

Metal not working (macOS)

CUDA not detected (Linux/Windows)

Web UI Issues

UI won’t load

UI shows “No models loaded”

Features not working

API Issues

401 Unauthorized

404 Not Found

500 Internal Server Error

Getting More Help

Collect diagnostic information

Check logs

Report issues

See Also