Troubleshooting

• Windows SmartScreen blocks it: click More info -> Run anyway.
• macOS says the app is damaged or cannot be checked: run xattr -dr com.apple.quarantine . in the extracted folder, then start it again.
• Linux: GLIBC_2.xx not found: your distribution is too old for the release build. Use the Docker image, or a newer distribution (Ubuntu 24.04 or later).
• "Address already in use": another program (or a second XianScan) uses port 8124. Close it, or start XianScan with a different port, for example PORT=8200 ./xianscan (PowerShell: $env:PORT=8200; .\xianscan.exe).

The translation model is not reachable.

• Using Ollama (the default): make sure Ollama is running and the model is downloaded (ollama list should show qwen3.5:9b, or whichever model you chose).
• Using a cloud provider: open Settings -> AI Translation Providers and click Test Connection. Check the API key and that your account has credit.
• After changing a provider's Endpoint Base URL: enter the API key again; a saved key never follows a provider to a new address.
• A page shows an error badge: open it in the Page Inspector and use Re-translate Page. The error text usually says what went wrong.

No installed font covers the target language's script. XianScan warns about this in the book editor and while translating. Open Settings -> Typesetting & Lettering, then pick a font for that script's row in the Fonts table, or choose Import font... in that dropdown. See Typography & Fonts.

A single letter such as É or ñ looked like a different font: older versions drew a letter the dialogue font does not have in a fallback font. XianScan now draws it plain (É as E) in the dialogue font itself, so every word stays in one font. To keep the accents, choose a dialogue font that has them, such as Poppins. See Typography & Fonts.

Open Settings -> Hardware & Compute to see the active device.

• Integrated graphics are skipped on purpose; only dedicated GPUs are used.
• Windows laptop with two GPUs: DirectML uses the adapter Windows lists first. Set xianscan.exe to High performance in Windows Settings -> System -> Display -> Graphics.
• Linux: CUDA needs the NVIDIA driver, CUDA 13 and cuDNN 9, and the archive's .so files must stay next to the program. Follow GPU Acceleration.
• It worked, then fell back to CPU: a GPU failed to start a model, so XianScan switched to the CPU. Fix the cause, then select the GPU again in Hardware & Compute or restart.
• Docker always runs on the CPU.

• The page does not load at all: LAN access is off, or XianScan was not restarted after turning it on. Check Settings -> Network & Access. Also check that both devices are on the same network, and that your firewall allows port 8124.
• "Token rejected" (Browser Importer) or a 401 error (Mihon): the token was mistyped or regenerated. Copy it again from Network & Access.
• Mihon: "server address" rejected: remove the trailing slash, for example http://192.168.1.20:8124.

Ask on Discord or open an issue on GitHub. Include your system, the XianScan version (Settings -> About & Diagnostics), the console output, and for a bad page the Copy Debug text from the Page Inspector.