---
title: "LLMind troubleshooting — common errors and fixes | LLMind"
description: "LLMind troubleshooting: command not found, signature verification failed, unsupported file format, slow enrichment, missing XMP packet, permission denied, unknown namespace version. Diagnoses and fixes for the seven errors people hit."
url: https://llmind.org/docs/troubleshooting/
source_format: html
---
# 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](https://github.com/dmitryrollins/LLMind/issues) 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](https://llmind.org/spec/signing-scheme/) 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](https://llmind.org/learn/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](https://llmind.org/glossary/xmp-namespace/) — 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

-   [Recipes](https://llmind.org/docs/recipes/) — the seven common workflows.
-   [CLI reference](https://llmind.org/docs/cli/) — every command and flag.
-   [LLMind CLI](https://llmind.org/product/cli/) — install options and surface overview.
-   [MCP integrations](https://llmind.org/mcp/) — Claude Desktop, Cursor, and the filesystem MCP pattern.
-   [GitHub issues](https://github.com/dmitryrollins/LLMind/issues) — open a bug or feature request.
-   [Security](https://llmind.org/security/) — threat model and responsible-disclosure policy.