LLMind troubleshooting

Published 2026-05-02

LLMind troubleshooting — diagnoses and fixes for the seven errors people actually hit. If your symptom isn't covered here, open a GitHub issue with the command, the file type, and the full output.

Common errors

1. llmind: command not found

$ llmind enrich document.pdf
zsh: command not found: llmind

The CLI isn't on your $PATH. LLMind ships on PyPI; install it with pipx (or uv) and let it manage PATH for you: 

pipx install 'llmind-cli[all]'
pipx ensurepath
llmind --version

If the command still isn't found after opening a new terminal, check that pipx's bin directory is on your shell's $PATH (echo $PATH | tr ':' '\n' | grep -E '\.local/bin|pipx'). Make sure you ran pipx ensurepath at least once and restarted your shell.

2. Signature verification failed

$ llmind verify document.pdf
ERROR: signature verification failed

Two causes: either the file's bytes were modified after enrichment (e.g. someone edited the PDF), or you're verifying with a key that doesn't match the signing key. Check which by running llmind inspect document.pdf --layer=provenance — the provenance layer records which key signed the file. Confirm you're verifying with the same one. If the bytes were modified, re-enrich the new version. The signing scheme spec covers the threat model.

3. Unsupported file format

$ llmind enrich notes.docx
ERROR: unsupported format: docx

LLMind currently writes XMP into formats that have a defined XMP packet location: PDF, JPEG, TIFF, PNG, GIF, MP3, MP4, and a handful of others. .docx, .xlsx, and other Office Open XML formats use ZIP-based metadata with a different mechanism — not yet supported. Convert to PDF and enrich the PDF, or open a GitHub issue requesting the format.

3. Long enrichment time on large PDFs

Enrichment time scales with the structural-layer cost — primarily OCR pages and content tokens, not raw page count. A 200-page PDF that's already searchable text might enrich in 30 seconds; a 50-page scanned document with --ocr can take several minutes per file. Run with --no-ocr if you only need descriptive and structural-from-text, or pre-OCR the file with a specialist tool and pipe in the result. See OCR once, read forever for the workflow argument.

4. XMP packet not visible after enrichment

Some PDF readers (notably older Preview.app builds and some browser viewers) hide XMP from their info panel. The packet is still there. Verify with the CLI directly: 

llmind inspect document.pdf
# or, lower-level:
exiftool -XMP -b document.pdf | head -40

If the inspect output shows the layers, the file is enriched correctly regardless of what the GUI viewer shows.

5. Permission denied writing to file

$ llmind enrich /shared/document.pdf
ERROR: permission denied: /shared/document.pdf

LLMind enriches files in place — it needs write access to the source file. If the file is on a read-only mount or you don't have write permission, copy it to a writable location first, or run with --out=path/to/copy.pdf to write to a new file (the original is unchanged).

6. unknown namespace version when verifying

$ old-tool verify document.pdf
ERROR: unknown namespace version: 1.0

The file was enriched with a newer LRFS namespace version than the verifier supports. LRFS uses stable, versioned namespaces — v0.x readers can't parse v1.0 payloads. Update the verifier; or, if that's not possible, downgrade the enricher's --namespace-version flag to match.

Where to go next