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-depspip 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 → Endpointmodel— Model deployments → your deployment name, prefixedazure/. 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 rebuildA page came out wrong or thin
Check the record:
cat .deepdoc/generation_quality.jsonPages 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 30These 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): colorsNo 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-commandsWorking 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 deployChatbot
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.