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 and a fresh log is started, so the pair never takes more than about 10 MB of disk. This happens as the log fills, not only at startup, so a long-running watch or serve stays inside the same ceiling.

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.

To record less, or nothing, set the level: --log-level warn keeps the warnings and errors, and --log-level off writes no log at all. A scan's log names every file it read, so off is the setting for a machine that should not keep that list. PIICRAWLER_LOG_FILTER sets the same thing for every run on the machine, and the flag overrides it when you need one run's log back. See the CLI reference.

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.

A scan is stuck on "scanning"

A scan records its own status as it works, so one whose process is killed before it finishes (Ctrl+C, a crash, an out-of-memory kill, a reboot) never gets to write a final status. It keeps saying scanning in piicrawler scans and in the scan list, however long ago it stopped.

Clear it with:

piicrawler scans prune

That marks every interrupted scan stopped, keeping what it had already found. Only run it when no scan is in progress: PII Crawler cannot tell an abandoned scan apart from one another process is still working on, so pruning during a live scan marks that one stopped too. The terminal UI and the web UI do the same cleanup on startup, so opening either also clears a stuck scan.

To remove the scan altogether, findings and all, use piicrawler scans delete <id>.

"There is no terminal to draw the interactive UI on"

Run with no arguments, PII Crawler opens its interactive terminal UI, and that needs a terminal to draw on. Three situations do not have one, and all three now say so and exit rather than failing obscurely:

• Over ssh without a terminal. ssh myhost piicrawler gives the remote command a pipe, not a terminal. Ask for one with -t:

  ssh -t myhost piicrawler

• From a script, a cron job or CI. There is no terminal to attach at all. Name what you want done instead of opening the UI, for example:

  piicrawler scan /srv/share --json

  Or serve the web UI and point a browser at it: piicrawler serve.

• With the output redirected. piicrawler > out.txt sends the UI's drawing to the file instead of to your screen, so there would be nothing to look at and no way to see what you were typing. Leave the output on the terminal, and capture results with a command that produces them: piicrawler scan /srv/share --json > findings.json.

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.