Troubleshooting
When a render goes wrong, Castwright names the failure instead of shrugging. This page lists the common questions first, then every failure the app can name. The same entries live inside the app under Help — the ”?” in the top bar — and a failed chapter deep-links straight to its entry, so you are never matching error text by hand.
Common questions
The app won’t start
One command starts everything: run npm start from the install folder and it brings up the web app, the server, and the TTS sidecar together. If the browser tab opens but stays blank, hard-refresh (Ctrl+Shift+R). If the terminal shows a port-in-use error, another copy is already running — close it first. On a fresh install, run npm install once before the first start.
Voices or models are missing
Open the Model Manager (under the account menu, or #/models) to see what is installed. The Kokoro voice pack installs with the install-kokoro script in the sidecar’s scripts folder; other engines install from their Model Manager rows. If an engine shows as installed but synthesis fails with “model not loaded”, load it from its pill in the top bar and wait for the pill to turn green.
Generation is much slower than usual
The usual culprit is a crowded GPU. Check it isn’t sharing the card with something heavy (a game, a second model), and keep only one heavy TTS model loaded — unload the analyzer Ollama or a second engine from the model pills. When the GPU runs out of VRAM it spills to system memory, which is much slower; the Model Manager shows current usage. If the sidecar started in CPU mode (a device=cpu line in the log at startup), synthesis will be slow by design. And if the slowdown crept in after hours of generating, restart the TTS sidecar — it reclaims leaked memory. The Admin view’s Resource trends panel shows the per-chapter speed history.
GPU not detected
If Castwright reports no GPU, or falls back to CPU unexpectedly: make sure your NVIDIA drivers are up to date, check that CUDA is installed and visible to the system (the Model Manager’s resource panel shows detected VRAM), and on Windows confirm the app is not being forced onto the integrated GPU via the graphics control panel. Still nothing? Email hello@castwright.ai with the output from the log panel.
Audio has glitches or artefacts
Occasional clicks, distortion, or truncated words usually trace to one of three things: a sentence too long for the model (split it in two in the manuscript editor); a very quiet or very loud segment skewing the loudness pass (re-generating the chapter is the fastest fix); or a model weight file that did not download cleanly (remove and reinstall the engine from the Model Manager).
My phone can’t reach the app
Real devices need the LAN HTTPS mode: run npm run dev:lan (or npm run start:lan for the production build) and open the printed https:// address. Each device must trust the local certificate once — run npm run install:cert-mobile and follow the per-OS steps it prints. Both devices must be on the same network.
Where are my books and audio on disk?
On your machine, in the open — nothing is hidden in a database. Each book lives in its own folder under the workspace directory (the castwright-workspace folder next to the install, by default): the manuscript, the cast (cast.json), per-chapter audio, and exports. Deleting a book folder removes that book; back up the workspace folder and you’ve backed up your whole library.
Failures during generation
Chapter synthesis timed out
What you saw: synthesis timed out for one chapter — the engine stalled mid-render, often while the sidecar was reclaiming memory. The chapter was skipped so the queue could advance.
What to do: click Retry on the chapter. If it times out repeatedly, restart the TTS sidecar to clear a wedged GPU state, then retry.
TTS sidecar not running
What you saw: the local TTS sidecar — the process that does the actual speaking — was not running.
What to do: start it (npm start launches it automatically), wait for the sidecar pill in the top bar to go green, then resume the run.
TTS engine keeps restarting
What you saw: the engine restarted repeatedly while rendering one chapter.
What to do: the sidecar is likely thrashing — usually too little VRAM or RAM headroom. Restart the TTS sidecar and/or lower generation concurrency, then retry.
GPU out of memory (VRAM)
What you saw: the GPU ran out of video memory mid-render — too many models were resident at once.
What to do: unload any models you are not generating with (the analyzer Ollama, or a second TTS engine) from the model pills, then retry. On an 8 GB card, keep only one heavy TTS model loaded.
Computer ran out of memory
What you saw: the operating system killed the TTS sidecar — the machine ran out of RAM.
What to do: close other memory-heavy apps and retry. If it recurs, restart the sidecar to reset its memory, then resume.
GPU error (auto-recovering)
What you saw: the sidecar hit a CUDA error and restarted itself — once the GPU context is corrupted, only a fresh process recovers.
What to do: wait about ten seconds for the sidecar pill to go green again, then click Retry. If the same chapter fails again, check the sidecar log’s text_preview= line — the culprit is usually a stray zero-width or control character in the manuscript.
TTS model not loaded yet
What you saw: synthesis was requested before the model finished loading.
What to do: load the engine from its model pill (or wait for the auto-load to finish — the pill turns green), then retry the chapter.
Voice catalog out of sync
What you saw: the engine rejected a speaker — the voice catalog no longer matches the loaded model.
What to do: stop the TTS sidecar, re-run the speaker-manifest audit, then restart the sidecar and regenerate the chapter.
Disk full
What you saw: the workspace drive is out of space — the chapter audio could not be written.
What to do: free up space on the workspace drive (delete old exports, or move the workspace to a larger drive), then retry the chapter.
Failures during analysis
Analyzer not reachable
What you saw: the analyzer could not be reached or stopped responding — the local Ollama daemon is down, or the analyzer service returned a server error.
What to do: check that Ollama is running (ollama serve), or switch the analyzer to Gemini (ANALYZER=gemini plus a GEMINI_API_KEY in server/.env). Then retry the chapter or resume the run. Worth knowing: when a Gemini key is set, an unreachable Ollama silently retries against Gemini — so this error usually means no fallback was configured, or both failed.
Analyzer rate-limited
What you saw: the free cloud tier rate-limited the run, so Castwright stopped rather than keep hammering the API.
What to do: wait for the quota window to reset (the free tier resets daily), or switch the work to a local model, then resume.
Analyzer daily quota exhausted
What you saw: the analyzer’s free-tier daily quota is used up for the day.
What to do: switch to a different analyzer model — each model has its own daily bucket (GEMINI_MODEL in server/.env, or Advanced Settings) — use the local Ollama analyzer, or wait for the reset time shown in the error.
Analyzer reply cut short
What you saw: the analyzer model cut its reply short — a chapter section was too large for one attribution call, even after automatic re-splitting.
What to do: retry the chapter. If it recurs, lower the stage-2 chunk budget in Advanced Settings, or switch to a stronger analyzer model.
Chapter attribution incomplete
What you saw: some lines in the chapter may be unattributed — the analyzer’s answer did not cover every sentence, so the best take was kept and the chapter was flagged.
What to do: click Retry on the chapter to re-run attribution. Already-attributed lines are kept; a retry usually fills the gaps.
Gemini API key problem
What you saw: Gemini authentication failed.
What to do: check that GEMINI_API_KEY in server/.env is set and valid, restart the server, then retry.
Still stuck?
Email hello@castwright.ai with the chapter number, the engine in use, and any error message from the log panel — we’ll help you sort it out.