Troubleshooting

English · 简体中文 · 日本語

Troubleshooting

Start with the first failing step and its actual error. Save your work before changing dependencies or configuration, and try the fix on a short passage before rerunning a whole book. Reset deletes active project data and settings; it is not a routine repair step.

Return to Home · Related: Updates and Backups

Collect the useful evidence

• In Pinokio, open Terminal; while startup is incomplete, open Starting to see the process output.
• For a running task, read the log in its tab. Reports → Runs records run history, and Review Checkpoints helps identify retained review work.
• Record your operating system, GPU/driver, installation method, exact task, model, and the first complete error message. Include the checkout revision when reporting a bug.
• From the checkout root, run python env_doctor.py; add --voice-tools for advanced native environments or --json for structured output.
• For Voice Lab, use Copy diagnostics or Download diagnostics. Review even sanitized output before posting it. Remove credentials, private book excerpts, voice recordings, and unnecessary personal paths.

Environment checks do not render audio or prove GPU compatibility. This guide was checked against code and UI, without an application/GPU runtime test.

Every model reply during script generation is in logs/llm_responses.log (review: logs/review_responses.log). The *.requests.log file beside each holds the exact request behind every reply, matched by its request= id, so a bad reply can be replayed. Check both for private book text before attaching them to a report.

The app will not start or Open Web UI never appears

1. Look for ModuleNotFoundError, ImportError, “Address already in use,” or the first traceback in the launcher terminal.
2. Confirm the core Install completed. The app expects its own app/env, not whichever python happens to be on your shell's PATH.
3. If a dependency is missing, stop the app and use Reinstall, then recheck the terminal. Do not install arbitrary new PyTorch packages over the platform-specific stack.
4. If an existing environment uses a different Python version, note that the optional attention wheels in the installer require CPython 3.10. A fresh install uses 3.10; an existing environment is not recreated automatically. Back up data before any environment rebuild.
5. For a port conflict in a direct launch, stop the conflicting service or use a free ALEXANDRIA_PORT. Pinokio chooses a port; follow its current Open Web UI link rather than an old bookmark.

Docker-specific: check the container startup output, NVIDIA runtime configuration, and the supplied loopback port mapping. The Compose file is an NVIDIA setup, not a generic AMD GPU configuration. See Installation.

Configuration edits appear to be ignored

Test Connection does not save settings. Click Save Configuration, including after changing LLM Location, and wait for save feedback.

If Setup shows a loading warning, use Retry loading configuration and resolve that error before overwriting settings. If you use custom environment variables, check the actual ALEXANDRIA_CONFIG_PATH and ALEXANDRIA_DATA_DIR; there may be a different settings file from the default app/config.json.

The bundled Pinokio Start LLM launcher edits the default app/config.json. Check Setup manually if your active configuration lives elsewhere.

LLM connection or script generation fails

Work through these in order:

1. Is the API server running, and is the intended model loaded?
2. Does Base URL point to its OpenAI-compatible API, usually ending in /v1? Is it reachable from Alexandria's host/container?
3. Does Model Name exactly match the served ID? Use its refresh icon to inspect the model list.
4. Is API Key valid for that server? For env:NAME, is the variable present in the process that runs Alexandria?
5. What does Test Connection report: URL validation, model listing, or completion? A failed model-list probe can identify a wrong API route or authentication problem before book processing.
6. After a successful probe, save the configuration and try Test this book with the LLM or a short generation.

Inside Docker, localhost points to the container. A server running on your host needs a container-reachable address. A port-forwarded remote server may look local; set Runs on this machine's GPU? according to where computation really happens.

The model answers, but the script is rejected

The pipeline expects specific structured replies and checks source preservation. A reachable server can still return malformed JSON, incomplete text, reasoning instead of an answer, or incorrect annotations.

• Use an instruction-following model and its supported reasoning/non-thinking controls. Do not rely on banning <think>.
• Remove unsupported custom headers/body parameters when isolating a provider error.
• Check context/output limits and start with a smaller passage or conservative generation settings.
• Inspect errors and retained checkpoints instead of deleting them. Repeatedly retrying the same invalid output may spend time or API credit without fixing the cause.
• Use manual transport when you want to supply each reply, and paste the final answer only.

For source fidelity, review, snapshots, and resume controls, see Scripts and Review. Connection, cost, and privacy details are in LLM Setup.

Manual mode has no visible prompt during a test

Skip Test Connection and Test this book with the LLM in manual mode. The current probes do not support the normal manual reply flow; a book preflight can wait for a reply that is not exposed in the usual panel. Use Cancel book test, upload a short excerpt, and use ordinary Generate Annotated Script instead. Complete its Your turn prompts with Copy prompt, Model reply, and Submit reply.

Rate limits, timeouts, and paused jobs

Check the provider's availability and limits before raising retry counts. Minimum interval (seconds) can space requests; Request timeout (seconds) can accommodate a slow working model. Neither fixes wrong credentials or an invalid request.

When retries run out controls whether the chunk fails or the run waits for you. Fix the endpoint before resuming. Automatic failover may switch to a remote/billed provider, so review both profiles and the disclosure settings.

Process Pause/Resume is unavailable on Windows. For script generation, Cancel followed by Generate Annotated Script can resume a retained compatible checkpoint. Do not assume this applies to every advanced task or that changed inputs/settings reuse the same checkpoint.

A first render seems stuck

First use may download a TTS model, load its weights, or warm up kernels. Watch the terminal and network/disk activity before assuming the process has hung. Compile Codec currently has no effect, so it is not the cause of a slow first run.

If the log reports a download failure, check network access, available disk space, and Hugging Face availability. Model weights are separate from the app's Git checkout. Use an authorized HF_TOKEN if model access or rate limits require it; do not post the token in logs or issues.

For restricted networks, configure any download endpoint or mirror deliberately before launching. A third-party mirror changes whom you trust for downloaded files and possibly credentials; do not use an unknown mirror or copy a token into an untrusted endpoint. Preserve existing cache data unless you have identified a corrupt asset.

The app uses CPU even though I have a GPU

Read the startup warning and identify the installed PyTorch build. Device: auto resolves to CUDA/ROCm, then MPS, then CPU. A GPU that is physically present but unavailable to PyTorch can indicate a driver/build/environment mismatch.

• On AMD/Linux, check the actual GPU/driver/ROCm combination. PyTorch's cuda namespace is also used for ROCm.
• On AMD/Windows, the current app resolver does not use DirectML acceleration; installed DirectML packages do not establish a GPU TTS path.
• On Apple Silicon, MPS must be reported available by PyTorch. A package install alone does not verify model operation.
• If a later package installation replaced GPU-specific PyTorch, use the appropriate project installer and inspect its output rather than blindly upgrading torch from a generic package index.

See the source-based hardware caveats in Installation. Do not assume one person's GPU benchmark applies to your system.

Out-of-memory errors or poor throughput

1. Lower Parallel Workers and Max Items/Batch in Setup.
2. Close other GPU-heavy jobs and check whether an LLM shares the same card.
3. Set Runs on this machine's GPU? accurately so the app can coordinate LLM and audio jobs. An incorrect “No” can allow competing work.
4. Leave Compile Codec off; it currently has no effect on speed. Run Auto-configure to pick a batch size for your card.
5. If Review Script stops at once saying the GPU is already full, free the memory (for example, unload the model holding it) and start review again.
6. Retry a small set of pending chunks before a full book.

Render Pending automatically uses local batches where supported. Voice Design and Character Ensemble paths run sequentially, so increasing workers is not a universal speed fix. CPU can be a fallback, but it may be unsuitable for long jobs. See Rendering and Export.

Clone voices fail validation or sound wrong

• Use a clean reference recording and an exact transcript of its spoken words.
• Imported references must meet the app's duration and audio-quality checks; the documented duration window is 3–30 seconds. Read the specific validation result.
• Confirm the file still exists and is accessible to the machine running Alexandria. A path on your laptop is not automatically available inside a container or on a server.
• Confirm you have the rights to use the recording and voice.
• Clone generation does not use per-line instruct directions as Custom, LoRA, or Voice Design does. Changing those directions is not a fix for a poor clone reference.

Listen to a few representative lines before rendering the book. See Voices for selecting the appropriate voice type and Rendering and Export for targeted regeneration.

TTS or exports fail

For external TTS, confirm TTS Mode: external, the Gradio server URL, and that the service is running. The external path supports Custom and Clone voices; local-only voice paths need local TTS. Check External call timeout (s) for slow external calls.

For local TTS, start with the first model-loading/rendering error, memory use, and the affected speaker's configuration. Do not repeatedly merge a book with failed or missing chunks; resolve readiness warnings first.

Tiny, broken, or missing MP3 output

MP3 encoding requires an FFmpeg build with MP3 support. On systems with a POSIX shell, inspect:

ffmpeg -encoders 2>/dev/null | grep mp3

On Windows, run ffmpeg -encoders and look for an MP3 encoder such as libmp3lame. Check the FFmpeg executable available to the app environment, especially if multiple installations exist.

Individual chunks may fall back to WAV when MP3 encoding fails; merged MP3 still needs a working encoder. Fix the actual FFmpeg installation rather than deleting valid generated audio. For M4B and chapter/Audacity export requirements, use Rendering and Export.

Preparer or Voice Lab says a tool/model is missing

Run Install Voice Tools (Optional) while the app is stopped, then check python env_doctor.py --voice-tools.

• Preparer normally uses preparer_env; a separate Voice Lab interpreter is not automatically a complete substitute.
• Enter real local GGUF paths. The Preparer's “optional, default from Setup” label should not be relied on: a normal preparation run requires the primary model file.
• Diarization requires compatible pyannote dependencies in the Preparer interpreter, a token, and Community-1 model access. The shipped optional installer provisions it only on Linux AMD.
• Voice Lab Profile needs llama-cpp-python and the profiler GGUF; Train needs the selected interpreter's training dependencies.
• If preflight says inputs changed, inspect the current settings/datasets and run a fresh preflight. Do not bypass it.
• Native compiler/SDK build errors cannot be fixed merely by refreshing the web page.

See Optional Voice Tools for setup and training boundaries.

Garbled characters or text-integrity warnings

Confirm the source text is valid UTF-8 and matches the intended edition. The app can repair some known encoding problems in memory, but unresolved cases are reported. Keep an untouched source copy.

Read the text-integrity report before accepting a merge. A changed word, missing span, or wrong speaker needs review; a successful API call is not proof of faithful narration. Use the focused checks and repairs in Scripts and Review.

When reporting an issue

Give enough information to reproduce a small failing case: revision, installation method, OS/GPU, relevant settings, exact operation, expected result, actual result, and the first error. Describe whether the failure occurs with one short sample or only a larger job. Report a test as passed only if you actually ran it.

Do not attach your full configuration, copyrighted/private book, or another person's voice recording without checking what it contains and whether you may share it. A short redacted log is usually a better starting point.

Sources

Verified against shipped main at 8c7a33cb310ab9264594a09ca27e48271585094f: README troubleshooting, launcher startup, UI controls, device resolution, LLM connection test, manual requests and book preflight, environment diagnostics.