Troubleshooting

August 31, 2026 · View on GitHub

First-run problems, in the order people actually hit them. If your symptom isn't here, open an issue with the checklist at the bottom.

Table of contents

Get more output first

Before anything else, make the tool tell you more. Cheapest lever first.

-v — verbose. Prints the build banner, the GPU devices it found, the resolved model path, and per-stage progress. Put it on every run you intend to report. For library / bindings use, where there is no CLI flag to pass, set CRISPASR_VERBOSE=1 instead.

--dry-run-resolve — which files, without opening them. This prints every path CrispASR would use and then exits. Nothing is loaded, so it still works when the real run crashes:

$ crispasr --backend kokoro -m auto --tts "x" --tts-output y.wav --dry-run-resolve
model:
  requested: auto
  backend:   kokoro
  registry:  kokoro-82m-q8_0.gguf
  url:       https://huggingface.co/cstr/kokoro-82m-GGUF/resolve/main/kokoro-82m-q8_0.gguf
  size:      ~135 MB
  status:    cached/local
  path:      /home/you/.cache/crispasr/kokoro-82m-q8_0.gguf
companion:
  ...

Read the status: and path: lines. This separates finding a file from loading it — which is the key split when a run dies during startup — and it also catches the case where a companion file (codec, voice pack) is the one actually missing. Compare the size: against the file on disk: a truncated or half-downloaded GGUF is a common and completely silent cause of trouble.

Capture the whole log. Almost all diagnostic output goes to stderr, and a bare > redirect captures only stdout — so "there was no output" is sometimes a capture problem rather than a program problem. Grab both streams:

crispasr ...args... *> crispasr-log.txt          # PowerShell 7+

crispasr ...args... > crispasr-log.txt 2>&1      REM cmd.exe

crispasr ...args... > crispasr-log.txt 2>&1      # Linux / macOS

Deeper levers, when the above isn't enough:

LeverWhat it adds
-debug / --debug-modeExtra decoder-level diagnostics (whisper-family backends).
GGML_SCHED_DEBUG=2Which backend each graph node was placed on — for "correct on CPU, wrong on GPU".
CRISPASR_<BACKEND>_DEBUG=1Per-backend step diagnostics. See environment-variables.md.

It printed the banner, then nothing happened

Symptom: the build-info banner and some crispasr[verbose]: lines appear, then the program stops. No error, no output file, no obvious clue.

This is almost always a crash, not a silent refusal. Every failure path in the CLI prints something before returning, so "no message" means the process died rather than returned. On Windows in particular the console swallows the fault and you get no dialog and no text (this is what #380 and #397 both looked like).

Step 1 — read the exit code. This is the single most informative thing you can send us, and it takes one command:

# PowerShell, immediately after the failing run
$LASTEXITCODE

REM cmd.exe
echo %ERRORLEVEL%

# Linux / macOS
echo $?
Exit codeHexMeans
-10737417950xC000001DIllegal instruction — the binary uses a CPU feature this machine lacks. See below.
-10737418190xC0000005Access violation (segfault). A genuine bug — please report it.
-10737407910xC0000409Stack buffer overrun / fail-fast. Please report it.
139—Segfault on Linux/macOS. Please report it.
132—Illegal instruction on Linux/macOS.
11, 12, 13, 14—Not a crash — a normal error return. CrispASR printed a reason; scroll up.

Step 2 — if it's an illegal instruction, you are on the wrong build for your CPU. The default Windows CPU zip targets an AVX2 + FMA baseline (Intel Haswell 2013+ / AMD Excavator 2015+). On an older CPU, download crispasr-windows-x86_64-cpu-legacy.zip instead — a generic x86-64/SSE2 build that runs anywhere from Westmere up, just slower per core. Recent builds check this at startup and print an explicit message naming the missing feature (CRISPASR_IGNORE_CPU_ISA=1 overrides the check). Full detail: install.md § Windows CPU: which zip?.

Step 3 — if it's an access violation, narrow where it dies before reporting. Add -v and note the last line printed:

Last line you seeWhere it died
resolved model = '...'Loading the model — the file was found, and opening/parsing it crashed.
backend '...' initialised OKAfter load — during synthesis or transcription.
nothing past the bannerStartup, before any model work. Usually the CPU-ISA case above.

Two follow-ups narrow it further, and neither can crash the way the real run does: --dry-run-resolve confirms the files it was about to open really are on disk and the expected size, and --no-gpu tells a GPU fault from a model fault.

On Windows, a minidump pins it exactly. The repo has a ProcDump recipe: windows-illegal-instruction-dumps.md. Use the default minidump, not -ma — a full dump can contain your audio, model data, and file paths.

Is it the GPU?

One flag answers this. --no-gpu forces the whole pipeline onto the CPU:

crispasr --backend kokoro -m auto --tts "test" --tts-output out.wav --no-gpu
  • Works with --no-gpu, fails without it → a GPU-backend problem. Tell us your GPU, driver version, and which zip/tarball you downloaded.
  • Fails both ways → not the GPU. The model, the file, or the CLI arguments.

Note that the -hip / -vulkan builds require the matching GPU driver and do not silently fall back to CPU. The Linux -cuda / -cuda13 tarballs do fall back since v0.8.30 (dynamic backend loading) — see install.md. Passing --no-gpu to such a build is fine; it just uses the CPU path.

model '...' not found locally

CrispASR does not download models unless you ask it to. When the file isn't there you get an explicit block naming the file and its size:

crispasr: model 'parakeet-tdt-0.6b-v3-q4_k.gguf' not found locally.
  Available for download: parakeet-tdt-0.6b-v3-q4_k.gguf (~467 MB)
  Use --auto-download or -m auto to download automatically.

Three ways forward:

crispasr --backend parakeet -m auto -f audio.wav              # resolve + download
crispasr --backend parakeet -m name.gguf --auto-download -f audio.wav
crispasr --backend parakeet -m /full/path/to/name.gguf -f audio.wav

A bare explicit filename is searched unchanged in --cache-dir, CRISPASR_CACHE_DIR, and CRISPASR_MODELS_DIR before CrispASR consults the registry. This matters for community models such as Piper voices: asking for piper-en_GB-cori-medium-f16.gguf must never silently substitute the registry's US Lessac default. If the file is elsewhere, pass its full path or set one of those model-directory options.

Downloads land in ~/.cache/crispasr/ — on Windows %USERPROFILE%\.cache\crispasr (override with CRISPASR_CACHE_DIR). To see exactly which paths would be used without running anything, use --dry-run-resolve.

If you do not see this block, the file was found. That matters when diagnosing a crash: it means the problem is in loading the file, not locating it.

Windows: which download, and the CUDA DLLs

ZipUse when
crispasr-windows-x86_64-cpu.zipDefault. Needs AVX2 + FMA (2013+ Intel / 2015+ AMD).
crispasr-windows-x86_64-cpu-legacy.zipOlder CPU, or the AVX2 build died with 0xC000001D.
crispasr-windows-x86_64-cuda.zipNVIDIA GPU. Self-contained, CUDA 12 runtime. Any GPU from Pascal (GTX 10xx) up.
crispasr-windows-x86_64-cuda13.zipNVIDIA GPU, Turing (GTX 16xx/RTX 20xx) or newer. Self-contained, CUDA 13 runtime (#400).
crispasr-windows-x86_64-cuda-non-cuda.zipAs -cuda.zip, and you already have the three CUDA 12 runtime DLLs.
crispasr-windows-x86_64-cuda13-non-cuda.zipAs -cuda13.zip, and you already have the three CUDA 13 runtime DLLs.
crispasr-windows-x86_64-vulkan.zipCross-vendor GPU (AMD/Intel/NVIDIA).

Each CUDA package bundles the runtime DLLs of its own major — the -cuda zips ship cudart64_12.dll / cublas64_12.dll / cublasLt64_12.dll, the -cuda13 zips ship the *64_13.dll trio. Each trio is published once per release and shared by that major's zips; see install.md § Windows CUDA: split downloads and check the matching -runtime-sha256.txt manifest before reusing DLLs from an older download.

Consequences worth knowing:

  • A separate CUDA Toolkit install is not required — a self-contained zip ships what it needs, and either zip runs fine regardless of which (or no) CUDA toolkit is installed system-wide. All that matters is the NVIDIA driver: the -cuda13 zip needs a CUDA-13-capable driver (r580+), the -cuda zip runs on anything r525+.
  • The two runtimes are not interchangeable: *64_12.dll files do not satisfy the -cuda13 build and vice versa — the DLL names carry the major precisely so a mismatch fails loudly instead of misloading.
  • Picking between them: -cuda13 covers Turing (sm_75) through Blackwell — CUDA 13 dropped Maxwell/Pascal/Volta entirely, so GTX 10xx / P100 / V100 users must take the CUDA 12 -cuda.zip. On hardware both support, either works; prefer -cuda13 on a current driver stack.
  • If you took a -non-cuda zip, the three matching DLLs must sit next to crispasr.exe — take them from the release assets or from the bin directory of an installed toolkit of the same major.

On some Windows laptops the Vulkan device 0 is the Intel iGPU and the NVIDIA GPU is 1; if Vulkan looks unexpectedly slow, rerun with -dev 1.

A backend refuses to start

These are normal error returns — CrispASR prints a reason and exits non-zero.

MessageFix
backend '...' is not available in this build (rc 12)Backend name typo, or a build without it. --list-backends shows what this binary has.
failed to initialise backend '...' (rc 13)The line above it names the real cause — a missing codec, an unreadable model, a bad voice pack.
backend '...' does not support TTS (rc 14)That backend is ASR-only. --list-backends has a tts column.
voice cloning requires the --i-have-rights flag (rc 17)You pointed --voice at a recording. Add --i-have-rights to attest you have the speaker's consent. See eu-ai-act.md.
--voice is a WAV but --ref-text was not setCloning from a recording needs --ref-text "<exact transcript of that wav>".

What to put in a bug report

Paste all of this — it is usually enough to diagnose without a round trip:

  1. The full command, verbatim.
  2. The complete output with -v added, captured with both streams redirected (the build-info banner at the top is the important part — it names the version, the backends compiled in, and your GPU).
  3. The exit code ($LASTEXITCODE / echo $?).
  4. The --dry-run-resolve output for the same command — it shows which files were going to be opened and whether each is actually on disk.
  5. Which download you used — the exact zip/tarball filename, or the cmake line if you built it yourself.
  6. Whether --no-gpu changes anything.
  7. Model files: which GGUFs, from which HuggingFace repo, and their sizes on disk (a truncated download is a real and common cause).