context-kit/docs/troubleshooting.md

# Troubleshooting

## Run Doctor

```sh
bin/context-kit doctor
```

This checks Docker, Compose, images, the Docker network, SearXNG health, a real
web-search MCP initialize/tools-list exchange, 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
```

## Repeated Per-Project Containers

Current OpenCode and Claude snippets connect web search and docs directly to the
shared HTTP services. If every project still starts a web-search container,
regenerate the snippet, update the assistant configuration, and restart the
assistant:

```sh
bin/context-kit install opencode
bin/context-kit install claude
```

For the upgrade from `origin/main`, build and start once. `start` creates only
the missing web-search service and refuses to recreate existing services:

```sh
bin/context-kit build
bin/context-kit start
```

Context Kit never performs a global Docker prune. Inspect labeled resources and
their owners explicitly:

```sh
docker ps -a --filter label=dev.context-kit=true \
  --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Label "dev.context-kit.lifecycle"}}\t{{.Label "dev.context-kit.owner"}}\t{{.Label "com.docker.compose.service"}}'
```

Containers from the old per-call web-search launcher have an empty Compose
service and no lifecycle/owner labels. After all old assistant processes are
stopped, remove only the exact legacy container IDs you verified; do not use a
name-pattern or global prune.

Lifecycle commands for one Compose project use a canonical, uid-owned lock and
reject cross-user control. Failed startup removes only newly-created service
containers, restores existing container states by ID, and never removes the
network or cache volume. `start` uses Compose `--no-recreate`, leaving an
existing container unchanged when its image or environment differs from the
current Compose model; it never silently replaces that container. Inspect the
shared services without deleting them:

```sh
bin/context-kit status
docker compose -p "${CONTEXT_KIT_COMPOSE_PROJECT:-context-kit}" -f compose.yml logs web-search-mcp docs-mcp searxng
```

Use the protocol-level doctor check. `/healthz` also performs initialize and
tools/list rather than trusting the proxy's static `/status` metadata:

```sh
bin/context-kit doctor
curl http://127.0.0.1:8777/healthz
```

`bin/context-kit status` lists legacy labeled containers that have neither a
Compose service nor lifecycle label. This is diagnostic only; Context Kit never
auto-removes them. Stop their old assistant owners before removing individually
verified container IDs.

## 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`.

## SearXNG Returns Only Bing, or Google Is Empty

SearXNG is digest-pinned in `compose.yml`. `start` never replaces that
container, so an image or `settings.yml` change does nothing until you
recreate SearXNG explicitly:

```sh
docker compose -p "${CONTEXT_KIT_COMPOSE_PROJECT:-context-kit}" -f compose.yml \
  up -d --force-recreate --no-deps searxng
```

Then probe engines separately:

```sh
curl 'http://127.0.0.1:8099/search?q=test&format=json&engines=bing'
curl 'http://127.0.0.1:8099/search?q=test&format=json&engines=google'
```

Google is a scraper. A successful HTTP 200 with zero results usually means
the pinned image's parser/user-agent is stale, not that Google is disabled.
DuckDuckGo is omitted from `settings.yml` because it CAPTCHAs this host.

## Search Fallback and Chromium

`search_web` defaults to SearXNG (Bing and Google). If SearXNG fails or
returns no results, the MCP fallback order is DuckDuckGo, then Chromium Bing.
The Chromium Bing path is a last resort; `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.

`search_web` now returns bounded `diagnostics.attempts` entries. Check each
provider's `status`, `duration_ms`, `result_count`, and categorized error before
changing provider order. An optional Brave API fallback is enabled only when
`CONTEXT_KIT_BRAVE_SEARCH_API_KEY` is set.

`fetch_url engine=browser` invokes Chromium for JavaScript-rendered pages. Every
HTTP(S) GET is intercepted and fetched through vetted DNS addresses; non-GET
requests, private/localhost destinations, more than 100 requests, and more than
20 MiB total browser traffic are blocked. Use `engine=http` for ordinary pages.

## 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 Sources Report Refresh Errors

If `docs_sources` reports `last_error`, the service keeps the previous generation
searchable and records the failed check. 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` pre-creates these directories and `doctor` reports
existing directories that are not writable by the current user. The docs MCP
uses stateless HTTP sessions, so clients do not retain a session ID across calls.
Use `bin/context-kit docs-rebuild` after fixing the underlying error.