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:
- 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. - "The database file is locked." Another copy of PII Crawler is using the database, usually a command-line scan, watch mode, or the terminal UI running in another window. The app waits up to 30 seconds for the other copy to finish its current write before giving up, so this dialog means the database stayed busy longer than that. Close or finish the other copy, then launch PII Crawler again. Nothing is damaged and no data is lost.
Launching when a copy is already running
PII Crawler runs as a single instance. If you double-click the app (or the Start Menu shortcut) while a copy is already running, the second launch does not start a new server; it opens the web UI of the copy that is already running in your default browser. You can also just open http://localhost:3001 yourself. This is why you only ever see one PII Crawler window even after clicking the shortcut a few times.
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.