120 lines
3.6 KiB
Markdown
120 lines
3.6 KiB
Markdown
# Troubleshooting
|
|
|
|
## Run Doctor
|
|
|
|
```sh
|
|
bin/context-kit doctor
|
|
```
|
|
|
|
This checks Docker, Compose, images, the Docker network, SearXNG health, docs
|
|
HTTP readiness, and docs source configuration.
|
|
|
|
For release-grade MCP protocol checks, run:
|
|
|
|
```sh
|
|
scripts/release-check
|
|
```
|
|
|
|
Live provider checks are opt-in because search engines, remote docs, and model
|
|
downloads can fail independently of this repo:
|
|
|
|
```sh
|
|
CONTEXT_KIT_LIVE_CHECKS=1 scripts/release-check
|
|
```
|
|
|
|
## SearXNG Is Not Responding
|
|
|
|
Start it:
|
|
|
|
```sh
|
|
bin/context-kit start
|
|
```
|
|
|
|
Then check:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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 `docs_query` or `docs_refresh` downloads an embedding model and
|
|
embeds the requested docs sections lazily. 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. Set `CONTEXT_KIT_DOCS_PREINDEX=1` only if you want
|
|
startup to eagerly embed every configured source.
|
|
|
|
## 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:
|
|
|
|
```sh
|
|
docker compose -p "${CONTEXT_KIT_COMPOSE_PROJECT:-context-kit}" -f compose.yml logs 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:
|
|
|
|
```text
|
|
Permission denied: '/models/models--BAAI--bge-small-en-v1.5'
|
|
unable to open database file
|
|
```
|
|
|
|
Fix ownership and restart:
|
|
|
|
```sh
|
|
DATA_DIR="${CONTEXT_KIT_DATA_DIR:-${HOME:?Set HOME or CONTEXT_KIT_DATA_DIR}/.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.
|