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. 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
- Click More info
- Click Run anyway
Server Issues
Server won’t start
Check if port is in use:0.0.0.0 requires IZWI_API_KEY. Set one, or bind 127.0.0.1 (the default):
Can’t connect to server
-
Verify server is running:
-
Check the operational probes:
-
Check the correct URL:
-
From another device: the server listens on
127.0.0.1by default. Start it with--host 0.0.0.0and anIZWI_API_KEY(see Security And CORS). - Check firewall settings
-
A
403saying theHostheader is not allowed means the server is bound to loopback and was reached through another name (a reverse proxy that forwards the originalHost, or DNS rebinding). Make the proxy sendHost: 127.0.0.1:8080, or bind a network address with an API key.
Server crashes on startup
Check logs:- 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
Model won’t load
Insufficient memory: Check available RAM: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 --detailedshows 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_BYTESorIZWI_CUDA_MEMORY_BUDGET_BYTES, make sure the budget leaves room for the model.
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_BYTESorIZWI_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
-
Verify correct directory:
- macOS:
~/Library/Application Support/izwi/models/ - Linux:
~/.local/share/izwi/models/ - Windows:
%LOCALAPPDATA%\izwi\models\
- macOS:
- Check folder name matches expected variant name
-
Restart the server:
Performance Issues
Inference is slow
Use GPU acceleration: macOS (Metal):--features cuda,flash-attn or --features cuda,cudnn.
Use smaller models:
Qwen3-TTS-12Hz-0.6B-Baseinstead ofQwen3-TTS-12Hz-1.7B-BaseQwen3.5-0.8Binstead of a larger chat model
High memory usage
Unload unused models: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
Poor transcription quality
Improve audio quality:- Use a better microphone
- Reduce background noise
- Speak clearly
Long recording refused as too large
An upload over the limit returns413. 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:
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:CUDA not detected (Linux/Windows)
Check NVIDIA drivers:Web UI Issues
UI won’t load
-
Verify server is running:
-
Check the URL:
http://localhost:8080 - Clear browser cache
- Try incognito/private mode
UI shows “No models loaded”
-
Download a model:
-
Load the model:
- Refresh the page
Features not working
Ensure required models are loaded:API Issues
401 Unauthorized
A server bound to a network address requires itsIZWI_API_KEY:
- Send
Authorization: Bearer <key>orx-api-key: <key>. - For
izwiCLI commands, exportIZWI_API_KEYin the shell that runs them. - In the web UI, reload the page and enter the key when asked.
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 toserver.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
500 Internal Server Error
Check server logs:- Model not loaded
- Invalid request format
- Insufficient memory
Getting More Help
Collect diagnostic information
Check logs
Report issues
Open an issue on GitHub with:- Izwi version (
izwi version --full) - Operating system and version
- Steps to reproduce
- Error messages and logs