105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# Troubleshooting
|
|
|
|
## Run Doctor
|
|
|
|
```sh
|
|
bin/context-kit doctor
|
|
```
|
|
|
|
This checks Docker, Compose, images, the Docker network, SearXNG health, and
|
|
docs source configuration.
|
|
|
|
## 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 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```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/.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.
|