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:
  1. Go to System Settings → Privacy & Security
  2. Scroll down to find the Izwi message
  3. Click Open Anyway

macOS: Command not found: izwi

The CLI tools aren’t in your PATH. If you installed the desktop app, open Settings > System > Command line tool, select Install, then open a new Terminal window. If you installed with ./scripts/install-cli.sh, add ~/.local/bin to your PATH:

Linux: Permission denied installing .deb

Use sudo:

Windows: SmartScreen blocks installation

  1. Click More info
  2. Click Run anyway

Server Issues

Server won’t start

Check if port is in use:
Use a different port:
Check for existing Izwi processes:
“refusing to bind … without an API key”: a non-loopback host such as 0.0.0.0 requires IZWI_API_KEY. Set one, or bind 127.0.0.1 (the default):

Can’t connect to server

  1. Verify server is running:
  2. Check the operational probes:
  3. Check the correct URL:
  4. From another device: the server listens on 127.0.0.1 by default. Start it with --host 0.0.0.0 and an IZWI_API_KEY (see Security And CORS).
  5. Check firewall settings
  6. A 403 saying the Host header is not allowed means the server is bound to loopback and was reached through another name (a reverse proxy that forwards the original Host, or DNS rebinding). Make the proxy send Host: 127.0.0.1:8080, or bind a network address with an API key.

Server crashes on startup

Check logs:
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:
Ensure you have enough free space (models can be 1-10+ GB). Corrupted download:

Model won’t load

Insufficient memory: Check available RAM:
Try a smaller model or close other applications. For Qwen3.8-27B-FP8 on CUDA, inspect the loaded entry returned by /v1/health. A successful compressed load reports family_diagnostics.resident_representation as q8_0_requantized_projections_with_dense_bf16 and fp8_execution_mode as q8_0_fallback:<reason>. This is intended for 40/48 GB-class devices with a resource-fitted context, but admission can still fail when free VRAM or allocator headroom is insufficient. It is not a native FP8 mode; see the support matrix. For Qwen3.8 responses that stop with No finite Qwen3.8 sampling distribution, check family_diagnostics.optimization_evidence.cuda_kv_storage in the loaded model diagnostics. BF16 model activations must retain their exponent range: F16 KV conversion can turn a finite value into infinity and corrupt subsequent attention. Supported CUDA devices (observed compute capability 8.0+) now default to storage_dtype: bf16 and selected_provider: cuda_bf16, with the same KV memory footprint. Rebuild/restart and reload the model to apply the policy. Remove an explicit IZWI_QWEN38_CUDA_BF16_KV=0 override to use the default; that override remains available for controlled F16 comparisons. Sampling failures include the target/draft/bonus stage and bounded numerical diagnostics; retain those details if a failure recurs under BF16 KV. If the diagnostic reports phase=draft and finite=0, the optional MTP head has produced an unusable proposal. Izwi now discards that entire speculative round, restores its cache position and draft RNG, and uses target-only sampling for the rest of that request. This recovery is automatic with MTP enabled; other requests retain their own MTP policy. The warning records the failing position and draft depth, and optimization_evidence.counters.mtp_nonfinite_draft_fallbacks_total counts requests switched to target-only sampling. MTP cache maintenance continues to preserve the loaded adapter’s state contract, so recovery does not remove all MTP computation. It prevents an invalid optional draft from aborting a healthy target stream; it does not establish or repair the underlying source of the MTP NaNs. Target/bonus numerical failures and backend execution failures remain errors. For long-context requests, inspect runtime_metrics.kv_cache.models in the health/admin diagnostics. single_sequence_token_capacity is the largest sequence the fitted pools can retain, while full_context_sequence_capacity is how many such sequences fit concurrently. Each arena also reports token_capacity, full-request page claims, and workspace budget/high-water bytes. Izwi reserves the exact prompt plus requested maximum output logically before dispatch; reduce max_tokens or concurrency when that complete demand does not fit. It does not evict arbitrary tokens from an active full-attention sequence. CUDA_ERROR_OUT_OF_MEMORY should not be returned for ordinary managed-capacity pressure. If it appears after this version, capture the exact Git SHA, loaded model diagnostics, the managed-KV snapshots before/after the request, and the CUDA driver/device profile; treat it as an allocator/runtime defect rather than raising the advertised context limit. Corrupted model:

Nemotron 3.5 Transcribe refused at load: not enough memory

Nemotron-3.5-Transcribe-30B-A4B-FP8 needs about 31 GiB on Metal and CUDA and about 33 GiB on CPU, plus about 48 MiB per request in flight and its attention KV. Izwi works this out from the model’s config and refuses the load before reading any weights when the backend’s memory budget cannot hold it, so the refusal is quick and leaves nothing half-loaded.
  • Unload other models and load it again. izwi status --detailed shows what is loaded:
  • On a Mac, use one with 64 GB or more of unified memory. 48 GB is doubtful; smaller Macs cannot hold it.
  • On NVIDIA, 24–32 GB GPUs cannot hold it; plan on 48 GB or more. The GPU needs compute capability 8.0 or newer; an older one fails with “Nemotron 3.5 Transcribe needs a CUDA GPU of compute capability 8.0 or newer”.
  • If you set IZWI_CPU_MEMORY_BUDGET_BYTES, IZWI_METAL_MEMORY_BUDGET_BYTES or IZWI_CUDA_MEMORY_BUDGET_BYTES, make sure the budget leaves room for the model.
These figures are computed from the model’s published configuration.

Fish Audio Drama 3 refused at load: not enough memory

FishAudio-Drama-3 holds about 37 GiB of weights on CPU, Metal and CUDA, and its load briefly needs a little more, plus room for one request. Izwi works this out before reading any weights and refuses a load the backend’s memory budget cannot hold, with a message such as “Fish Audio Drama 3 needs about … GiB of … memory (… GiB of weights, a … GiB load peak, … GiB for one request); this device has … GiB”.
  • Unload other models and load it again:
  • On a Mac, use one with 64 GB or more of unified memory.
  • On NVIDIA, use a GPU with 48 GB or more and compute capability 8.0 or newer; an older GPU is refused before any weights are read.
  • If you set IZWI_CPU_MEMORY_BUDGET_BYTES, IZWI_METAL_MEMORY_BUDGET_BYTES or IZWI_CUDA_MEMORY_BUDGET_BYTES, make sure the budget leaves room for the model.

Fish Audio Drama 3 request errors

Model not detected after manual download

  1. Verify correct directory:
    • macOS: ~/Library/Application Support/izwi/models/
    • Linux: ~/.local/share/izwi/models/
    • Windows: %LOCALAPPDATA%\izwi\models\
  2. Check folder name matches expected variant name
  3. Restart the server:

Performance Issues

Inference is slow

Use GPU acceleration: macOS (Metal):
Linux (Docker CUDA):
Linux/Windows source build (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
  • Qwen3.5-0.8B instead of a larger chat model
Close other applications to free memory

High memory usage

Unload unused models:
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:

Poor transcription quality

Improve audio quality:
  • Use a better microphone
  • Reduce background noise
  • Speak clearly
Use a larger model:
Specify language:

Long recording refused as too large

An upload over the limit returns 413. The limits are 64 MiB for transcription jobs and the web UI, and 25 MiB by default for /v1/audio/transcriptions and izwi transcribe (set IZWI_OPENAI_AUDIO_UPLOAD_LIMIT_MB on the server to raise it). Uncompressed WAV is large: one hour at 16 kHz, mono, 16-bit is about 115 MB. A one-hour WAV is therefore refused, even with Nemotron-3.5-Transcribe-30B-A4B-FP8, which transcribes an hour in one pass. Compress it first; mono MP3 at 48 kbit/s is about 22 MB an hour:
FLAC is lossless but compresses speech much less, so a full hour may still be near 64 MiB.

Microphone not detected (Web UI)

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

GPU Issues

Metal not working (macOS)

Verify Apple Silicon:
Check macOS version:
Enable Metal:
Metal requires macOS 15 or later. On macOS 12-14, Izwi keeps running on CPU and an explicit Metal request reports a CPU fallback.

CUDA not detected (Linux/Windows)

Check NVIDIA drivers:
For Docker CUDA on Linux, verify the NVIDIA driver and container runtime. For source builds, verify CUDA Toolkit installation:
If you installed from source, rebuild with CUDA support:
Verify runtime backend state:

Web UI Issues

UI won’t load

  1. Verify server is running:
  2. Check the URL: http://localhost:8080
  3. Clear browser cache
  4. Try incognito/private mode

UI shows “No models loaded”

  1. Download a model:
  2. Load the model:
  3. Refresh the page

Features not working

Ensure required models are loaded:

API Issues

401 Unauthorized

A server bound to a network address requires its IZWI_API_KEY:
  • Send Authorization: Bearer <key> or x-api-key: <key>.
  • For izwi CLI commands, export IZWI_API_KEY in the shell that runs them.
  • In the web UI, reload the page and enter the key when asked.
A loopback-bound server (the default) needs no key; if you still get 401, check you’re connecting to the right server and that no proxy is interfering.

403 Cross-origin request rejected

The server rejects writes from web pages on other sites. If your own web app calls the API, add its origin to server.cors_origins (or IZWI_CORS_ORIGINS).

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:
Common causes:
  • Model not loaded
  • Invalid request format
  • Insufficient memory

Getting More Help

Collect diagnostic information

Check logs

Report issues

Open an issue on GitHub with:
  1. Izwi version (izwi version --full)
  2. Operating system and version
  3. Steps to reproduce
  4. Error messages and logs
GitHub Issues

See Also