Troubleshooting
Getting logs
Section titled “Getting logs”By default Piixie logs to the console only and writes no log files. To capture structured JSON logs for a bug report, launch the app with the PIIXIE_DEV=1 environment variable; log files then land in a logs/ folder inside the app data directory:
| Platform | Location |
|---|---|
| macOS | ~/Library/Application Support/Piixie/logs/ |
| Windows | %APPDATA%\Piixie\logs\ |
| Linux | ~/.config/Piixie/logs/ |
When something fails, the most recent log file usually names the cause. Logs are local files; nothing is reported anywhere.
Model download fails or stalls
Section titled “Model download fails or stalls”The first-launch download fetches ~5 GB from Hugging Face. If it fails:
- Check connectivity and disk space (the E4B model needs ~5 GB free, the 12B model ~7.1 GB)
- Corporate proxies and TLS-inspecting firewalls can break the download; try a different network
- A partially downloaded file is resumed or restarted on the next attempt
The model won’t start
Section titled “The model won’t start”Piixie spawns llama-server in the background. If the status never turns ready:
- Low memory is the usual cause. The E4B model wants roughly 6 GB of headroom; close other heavy apps or switch to the smaller model if you’re on the 12B
- Relaunch with
PIIXIE_DEV=1and check the newest log file for server startup errors - Quitting and relaunching the app restarts the server process cleanly
Runs are slow
Section titled “Runs are slow”Inference speed is hardware-bound. Options, in order of effect:
- Use the default E4B model rather than the 12B
- Offload inference to a GPU machine with server mode
- Use a remote endpoint if your data policy allows it
Long PDFs with many images are the heaviest case, since each image goes through vision analysis. Choosing auto-blur or text-only processing when prompted skips that work.
PII slipped through
Section titled “PII slipped through”No detector is perfect. If a run missed something:
- Append guidance to your profile’s prompt (“always treat project codenames like ORION as PII”) so future runs catch it
- The larger 12B model and frontier remote models catch more edge cases than the default model
- Re-run the file and compare the replacement tables; detection has some run-to-run variance
A remote endpoint won’t connect
Section titled “A remote endpoint won’t connect”- “Authentication failed”: the API key is wrong or lacks access
- “Could not reach the endpoint”: check the base URL, and remember it goes without the
/v1suffix - For self-hosted servers, confirm the server is reachable from your machine (
curl http://host:port/v1/models)
Output file looks wrong
Section titled “Output file looks wrong”Formatting issues in rewritten PDFs or DOCX files are bugs worth reporting. Keep the original file, note the mode and profile used (the history entry has the snapshot), and grab the matching log file.