Symptoms first, in the words the tool uses. If yours is not here, the codebase is open and the error messages say what file they came from.

"listen 127.0.0.1:11500 (already running?)"

hay serve found the port taken. Usually a daemon is already running, which is fine: every command talks to it automatically, and you do not need a second one. If something else owns the port, move Haypile:

hay serve --port 11600        # one-off
export HAYPILE_ADDR=127.0.0.1:11600   # permanent

Commands ignore the running daemon

The CLI refuses to route through a daemon serving a different database, which happens when the daemon was started with a different HAYPILE_DIR. It falls back to direct index access, so results are still correct; watching is what you lose. Fix by restarting the daemon under the environment you want:

hay stop
hay add ~/Documents      # restarts it with the current HAYPILE_DIR

"unsupported format (want .docx .htm .html .markdown .mbox .md .pdf .pptx .txt)"

You pointed hay add at a single file of a type Haypile cannot parse. This errors only for single files, because you named that file deliberately; folder indexing skips unsupported files silently.

`hay add` has been running for a long time

Working as designed: hay add waits for the whole pass, however long it takes, with no timeout. A large folder of PDFs can legitimately take an hour; the live progress line (or, in a pipe, the milestone lines) shows the phase, the fraction done, and the time left. Indexing also deliberately yields to your foreground work: the daemon runs at background priority and embedding leaves two CPU cores free, so a busy machine indexes slower than an idle one. If the progress line has genuinely stopped moving, check from another terminal: curl -s localhost:11500/api/status reports the in-flight pass under indexing.

"Warning: N files could not be read and were skipped."

Some files failed to open or parse: corrupt PDFs, permission problems, truncated downloads. One bad document never aborts an indexing pass, and if a previously indexed version of the file exists, it stays searchable until a readable version appears.

A scanned PDF returns no results

Pages that are images need a local vision model to transcribe them; without one they index empty. See Scanned PDFs (OCR). After setting a model up, re-index the source: hay remove <path> && hay add <path>.

`hay init` indexed fewer files than expected

Machine-managed directories are skipped on purpose: node_modules, vendor, venv, __pycache__, target, dist, build, coverage, Pods, DerivedData. Indexing a code project should surface your README and design notes, not thousands of dependency READMEs. Hidden directories like .git are skipped too. If a document you want lives in one of these folders, move it elsewhere or index that file directly with hay add <file>.

"no local LLM endpoint found"

hay ask needs an OpenAI-compatible server and probed the usual ports without finding one. Run hay llm setup for the guided path, or point at your server: hay ask --endpoint http://localhost:PORT/v1. Search never needs an LLM; only ask does.

Saved changes are not showing up in search

Check that the daemon is running with hay status; watching only happens while it is up. Files re-index within seconds of saving, so if the daemon is up and a result is still stale, re-run hay add <folder>. It is cheap (unchanged files are skipped) and reconciles everything, including deletions.

Index seems wrong in a way you cannot name

The reset is safe and complete, because the index is derived data:

hay stop
rm -rf ~/.haypile        # Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.haypile"
hay add <your folders again>

Your documents are untouched; only the index is rebuilt.

Troubleshooting