3.1 KiB
Troubleshooting
Run Doctor
bin/context-kit doctor
This checks Docker, Compose, images, the Docker network, SearXNG health, and docs source configuration.
SearXNG Is Not Responding
Start it:
bin/context-kit start
Then check:
curl 'http://127.0.0.1:8099/search?q=test&format=json'
If you changed CONTEXT_KIT_SEARXNG_PORT, use that port instead.
MCP Image Missing
Build default images:
bin/context-kit build
Fetch URL Says Max Download Bytes Is Too Big
If fetch_url fails before making a network request with an MCP validation error
like Number must be less than or equal to 26214400, rebuild the web-search MCP
image:
bin/context-kit build
Context Kit patches the upstream mcp-web-search schema so the accepted
max_download_bytes value matches CONTEXT_KIT_WEB_SEARCH_MAX_BYTES, which
defaults to 52428800.
Search Fallback and Chromium
search_web defaults to SearXNG. If SearXNG fails or returns no results, the
upstream fallback order is DuckDuckGo, then Bing. Bing uses Chromium through
Puppeteer, so bin/context-kit doctor checks that the configured Chromium path
exists inside the web-search image.
Context Kit carries a source-controlled Bing provider override in
docker/web-search/overrides/bing.js because the upstream 1.3.0 provider can
race result rendering and return no items even when Chromium sees Bing result
cards. The override waits for result cards and decodes current Bing redirect
URLs before handing results back to the upstream fallback registry.
fetch_url is different: in upstream mcp-web-search 1.3.0, engine=browser is
accepted but reserved for future support. It does not currently invoke Chromium;
URL fetching uses the HTTP extractor path.
Docs Indexing Is Slow
The first run downloads an embedding model and embeds every configured docs section. Keep default sources small, and add profiles only when you need them.
Cloudflare and other large docs sets can take significantly longer than the default source profile.
Docs Tools Say Index Manager Not Initialized
If docs_query or docs_refresh returns Index manager not initialized while
/status still responds, the HTTP wrapper is up but llms-txt-mcp failed to
initialize its embedding model or Chroma database. Check the container logs:
docker logs context-kit-docs-mcp
A common cause is Docker creating the bind-mounted cache directories as root
before Context Kit created them as the host user. Look for errors like:
Permission denied: '/models/models--BAAI--bge-small-en-v1.5'
unable to open database file
Fix ownership and restart:
DATA_DIR="${CONTEXT_KIT_DATA_DIR:-$HOME/.local/share/context-kit}"
sudo chown -R "$(id -u):$(id -g)" "$DATA_DIR/docs" "$DATA_DIR/models"
bin/context-kit restart
bin/context-kit start now pre-creates these directories and doctor reports
existing directories that are not writable by the current user. If an assistant
client reports Session not found after restarting docs-mcp, restart the
assistant so it opens a fresh Streamable HTTP MCP session.