Troubleshooting
When something goes wrong, start with the log file. PII Crawler writes one automatically on every run, including desktop launches where no terminal is attached.
Where the log file lives
| Platform | Path |
|---|---|
| macOS | ~/Library/Logs/PIICrawler/piicrawler.log |
| Windows | %LOCALAPPDATA%\PIICrawler\Logs\piicrawler.log |
| Linux | ~/.local/state/piicrawler/piicrawler.log (or $XDG_STATE_HOME/piicrawler/piicrawler.log if you have set XDG_STATE_HOME) |
On macOS you can also open the log through the built-in Console app: it appears under Reports → Log Reports as part of your user log folder, or just press Cmd+Shift+G in Finder and paste the path above.
When the log grows past 5 MB, it is moved aside to piicrawler.log.1 at the next launch and a fresh log is started, so the pair never takes more than about 10 MB of disk.
If you want the log somewhere else (for example when collecting logs from a fleet), set the PIICRAWLER_LOG_FILE environment variable to a full file path. It overrides the default location.
The app shows "PII Crawler failed to start"
If PII Crawler hits a fatal error while starting from the desktop (double-clicking the app on macOS, or the Start Menu shortcut on Windows), it shows an error dialog with the reason instead of silently refusing to launch. The same text is written to the log file at the path the dialog shows.
Common causes:
- Another copy is already running. The web UI port (3001) is taken. Close the other copy, or open
http://localhost:3001in your browser; the running copy is already serving it. - The database could not be opened or upgraded. Your scan database lives at
~/.piicrawler/piicrawler.db. If the dialog mentions a database or migration error, copy the exact message into a support request; do not delete the database, your scan history and triage verdicts are in it.
If the dialog itself is not enough to resolve the problem, send us the dialog text plus the last ~50 lines of the log file and we can usually pinpoint the cause quickly.
Starting from a terminal to see errors live
Every desktop launch is the same binary as the CLI. Running it from a terminal prints errors directly:
piicrawler serve
On macOS the bundled binary is inside the app: /Applications/PIICrawler.app/Contents/MacOS/piicrawler serve. On Windows it is piicrawler.exe serve in the install folder.