Reference

Reference

Troubleshooting

Common failures and what they actually mean.


Install and setup

tree-sitter takes forever to install

It compiles from source. Install the pure-Python dependencies first, then DeepDoc without re-resolving them:

pip install click litellm gitpython rich pyyaml jinja2
pip install deepdoc --no-deps
pip install "deepdoc[chatbot]" fails with ResolutionImpossible

You are probably on Python 3.15. The chatbot’s local embedding model (fastembed) needs onnxruntime, which only publishes wheels up to Python 3.14, and on Intel Macs only up to 3.13. Create the virtual environment with Python 3.10–3.14 (3.10–3.13 on an Intel Mac) instead:

python3.14 -m venv .venv && source .venv/bin/activate
pip install "deepdoc[chatbot]"
Chatbot sync failed: Could not load model nomic-ai/nomic-embed-text-v1.5

The first run downloads the embedding model from Hugging Face, which rate-limits anonymous downloads (HTTP 429). The docs are still generated; the run ends as partial. Wait a few minutes, then run deepdoc generate --force. Setting HF_TOKEN to a free Hugging Face token avoids the limit.

deploy refuses: unresolved quality issues

deepdoc deploy refuses while any page is failed or invalid; the error lists those pages. Plain deepdoc generate refuses because docs already exist, so regenerate with deepdoc generate --force. A failed chatbot sync alone does not block deploy.

update says there is no sync baseline

deepdoc update diffs from the last commit that was fully synced. If the first deepdoc generate had a failed page or a failed chatbot sync, no such commit exists yet. Run deepdoc generate --force once; later runs keep the last good baseline even if they end partial.

npx not found / serve or deploy fails immediately

Both shell out to Node. Install Node.js 18 or newer from nodejs.org. The Python side works without it; only previewing and building the site need it.

Azure: I do not know what to put in base_url or model

In the Azure Portal, open your OpenAI resource:

  • base_url — Keys and Endpoint → Endpoint
  • model — Model deployments → your deployment name, prefixed azure/. Your chosen name, not the underlying model.
  • api_version — the version your deployment targets, e.g. 2024-02-01

DeepDoc names whichever of these is missing rather than failing vaguely.

Gemini requests fail or authenticate oddly

Keep the gemini/ prefix on the model name. Without it LiteLLM may route to Vertex AI, which authenticates differently.

Generating

generate refuses to run because docs already exist

A guard against overwriting work. Choose one:

deepdoc update           # regenerate only what changed — usually right
deepdoc generate --force # refresh existing DeepDoc-managed pages
deepdoc generate --clean # delete owned files and state, then rebuild
A page came out wrong or thin

Check the record:

cat .deepdoc/generation_quality.json

Pages marked invalid or stub failed validation. Re-run update, or generate --force if several pages are affected. If it persists, the page is probably starved of evidence — a larger source_context_budget or a more capable model usually helps.

Rate limits / 429s

Lower the concurrency:

deepdoc config set llm.rate_limits.max_concurrency 2
deepdoc config set llm.rate_limits.requests_per_minute 30

These apply to documentation generation. The chatbot’s answer model is a separate surface and does not read them.

Not in a git repository

DeepDoc uses git to detect changes. Outside a repository it falls back to content hashing — which works, but update --since has nothing to diff against.

The site

My config change did nothing

Check which kind it is. Everything under site.* applies on the next deepdoc serve. Everything else — exclude, scan limits, the model — changes what gets documented and needs generate or update.

On a successful re-apply, serve says so:

Applied .deepdoc.yaml changes (no regeneration, no LLM calls): colors

No line means nothing changed. If you expected one, check for a typo — config set catches those, hand-editing does not.

deploy refuses to publish
Refusing to deploy docs with unresolved quality issues:
- invalid docs present: cli-commands

Working as intended — those pages did not generate cleanly. Fix them by regenerating, rather than working around the gate.

Pages are missing from the sidebar
2 page(s) are not in the sidebar: runbook, faq. Add them under site.nav.extra.

Hand-written Markdown renders and is reachable by URL, but the sidebar comes from the plan. Add them with site.nav.extra.

My theme preset was ignored

Seven presets exist: neutral, black, vitepress, ocean, catppuccin, dusk, purple. An unknown name warns and falls back:

site.theme.preset: 'solar' is not a known preset — using the default palette.
The favicon did not change

Browsers cache favicons hard. Hard-reload (⌘⇧R) before concluding it failed.

Links break when served under a subpath

Set the base path at build time:

NEXT_PUBLIC_BASE_PATH=/docs deepdoc deploy

Chatbot

Answers look wrong

Inspect what was retrieved, without paying for an answer:

curl -X POST localhost:8100/query-context -d '{"query":"how does auth work"}'

If retrieval missed the relevant files, the answer never had a chance.

First run downloads hundreds of megabytes

Expected. Embeddings default to local fastembed, which fetches its model once (~300 MB). No key and no external calls afterwards.

The chatbot cannot reach its backend in production

Set chatbot.backend.base_url to the deployed service and add your docs domain to chatbot.backend.allowed_origins, then rebuild.

CI

update does more work than expected in CI

A shallow clone has no history to diff against. Use fetch-depth: 0 on the checkout step.

A bad run published anyway

Add --strict-quality, which exits non-zero when any page fails validation instead of publishing it.

Still stuck

deepdoc status shows what exists and what is stale. deepdoc performance shows what recent runs actually did. Both are free and local.

Edit this page on GitHub