reference

Troubleshooting

Common issues with ingest, hybrid retrieval, Qdrant, embeddings, and agent skills.

Updated

Run the health check

Start with docmancer doctor to diagnose most issues:

docmancer doctor

It reports config status, SQLite index health, loader availability, Qdrant status, embeddings provider, vector / lexical drift, and installed agent skills.

"No results found" when querying

If docmancer query returns no results, check whether you have anything indexed:

docmancer list
docmancer inspect

If the list is empty, ingest first:

docmancer add https://docs.example.com
docmancer ingest ./local-docs

If sources are listed but a query returns nothing, try a broader query. Lexical mode matches exact terms — "login" will not match content that only says "sign in". Try --mode hybrid (or --mode dense) to catch semantic neighbours:

docmancer query "login" --mode hybrid --explain

Command not found: docmancer

The docmancer binary is not on your PATH. This usually happens after installing with pipx on a fresh system.

pipx list
pipx ensurepath

Restart your terminal.

Python version errors

Docmancer requires Python 3.11 through 3.13.

python3 --version

If you are on 3.10 or older, upgrade Python. If you are on 3.14+, pin an earlier interpreter:

pipx install docmancer --python python3.13

PDF / DOCX / RTF / HTML ingest fails

The optional loaders for these formats live behind the [local] extra:

pip install 'docmancer[local]'

If you already have the extra installed and ingest still fails, run docmancer doctor — the report includes a loader-availability section that pinpoints the missing dependency.

Playwright / browser errors

If docmancer add --browser fails with an import error, Playwright is not installed:

pip install 'docmancer[browser]'
playwright install chromium

If Playwright is installed but pages fail to load, the site may need additional browser setup. Try without --browser first — most documentation sites work with the default HTTP fetcher.

Qdrant fails to start

docmancer qdrant status shows what's happening. Common cases:

  • Port in use. Stop the conflicting process or wait for the existing Docmancer-owned instance to exit. The port selection is guarded by filelock so parallel docmancer calls don't race.
  • Foreign Qdrant. If you pointed vector_store.url at a pre-existing Qdrant collection, QdrantStore.ensure_collection refuses to claim it unless the Docmancer ownership sentinel is present. This is a safety feature. Either create a fresh collection or use a different Docmancer-owned URL.
  • Unsupported platform. When no matching Qdrant binary is available for your OS / arch, Docmancer transparently falls back to sqlite-vec. Check docmancer doctor for the active backend.

To restart cleanly:

docmancer qdrant down
docmancer qdrant up
docmancer qdrant logs

Vector / lexical drift

docmancer inspect warns when SQLite section counts and Qdrant point counts diverge. Common causes:

  • Running docmancer ingest --recreate cleared SQLite but Qdrant still has the old points. sync_vector_store now prunes vector points and embedding_upserts rows for chunk ids that have vanished from SQLite — re-run ingest to reconcile.
  • A source was removed via docmancer remove <source> but Qdrant points lingered from an older Docmancer version. docmancer ingest --recreate <source> will rebuild from scratch.

Embeddings: missing API key

Configured a cloud embeddings provider (OpenAI, Voyage, Cohere) but the API key env var is unset? Ingest does not abort — it falls back to FTS5-only with a warning, so retrieval still works in --mode lexical. Set the env var and re-run docmancer ingest to enable dense + sparse.

Agent does not pick up the skill

After install:

  1. Run docmancer doctor to verify the skill file exists.
  2. Check the skill file path matches what your agent expects.
  3. For Cursor: restart the editor (skills are not picked up mid-session).
  4. For Cline: enable Skills in Settings > Features, then restart VS Code.
  5. For Claude Code: skills are picked up immediately — no restart needed.

If the skill file exists but the agent still doesn't use it, the embedded binary path may be stale:

docmancer install <agent>

Stale or corrupted index

If queries return unexpected results, rebuild the index for one source:

docmancer ingest ./docs --recreate
docmancer add https://docs.example.com --recreate

Or clear everything:

docmancer remove --all

This clears all indexed content (SQLite + Qdrant points) but keeps your config.

pydantic or binary wheel errors

If you see cannot import pydantic_core after installation, the Python architecture may not match your system (common on Apple Silicon Macs with both arm64 and x86 Python installs):

pipx uninstall docmancer
pipx install docmancer --python /opt/homebrew/bin/python3

On Apple Silicon, prefer /opt/homebrew/bin/python3 (arm64) over /usr/local/bin/python3 (often x86).