Troubleshooting Guide

Common issues and solutions for Context Engine.

Documentation: README · Getting Started · Configuration · IDE Clients · MCP API · ctx CLI · Memory Guide · Architecture · Multi-Repo · Observability · Kubernetes · VS Code Extension · Troubleshooting · Development

On this page:

• Collection Health & Cache Sync
• Common Issues
• Connectivity Issues
• Endpoint Verification
• Debug Logging

Collection Health & Cache Sync

Automatic health checks detect and fix cache/collection sync issues.

Check collection health

python scripts/collection_health.py --workspace . --collection codebase

Auto-heal cache issues

python scripts/collection_health.py --workspace . --collection codebase --auto-heal

Detection scope

• Empty collection with cached files
• Mismatch between cached files and collection contents
• Missing metadata in collection points

When to use

• After manually deleting collections
• Searches return no results despite indexing
• After Qdrant crashes or data loss
• When switching between collection names

Automatic healing

Health checks run on watcher/indexer startup, clearing cache and reindexing when sync issues detected.

Common Issues

Tree-sitter not found or parser errors

Optional feature. If USE_TREE_SITTER=1 causes errors, unset it or install tree-sitter deps and reindex.

Tokenizer missing for micro-chunks

Run make tokenizer or set TOKENIZER_JSON to valid tokenizer.json. Falls back to line-based chunking.

SSE "Invalid session ID" when POSTing /messages directly

Expected behavior without SSE session initiation. Use MCP client (e.g., mcp-remote) for handshake.

llama.cpp platform warning on Apple Silicon

Prefer native path (scripts/gpu_toggle.sh gpu). For Docker, add platform: linux/amd64 to service or ignore during local dev.

Indexing stuck on large files

Use MAX_MICRO_CHUNKS_PER_FILE=200 during dev runs.

Watcher timeouts (-9) or Qdrant "ResponseHandlingException: timed out"

Set watcher-safe defaults to reduce payload size:

QDRANT_TIMEOUT=60
MAX_MICRO_CHUNKS_PER_FILE=200
INDEX_UPSERT_BATCH=128
INDEX_UPSERT_RETRIES=5
INDEX_UPSERT_BACKOFF=0.5
WATCH_DEBOUNCE_SECS=1.5

If issues persist, lower INDEX_UPSERT_BATCH to 96 or raise QDRANT_TIMEOUT to 90.

Connectivity Issues

MCP servers can't reach Qdrant

Confirm containers are up: make ps.

SSE port collides

Change FASTMCP_PORT in .env and mapped port in docker-compose.yml.

Searches return no results

Check collection health (see above).

Tool descriptions out of date

Restart: make restart.

Endpoint Verification

# Qdrant DB
curl -sSf http://localhost:6333/readyz >/dev/null && echo "Qdrant OK"

# Decoder (llama.cpp sidecar)
curl -s http://localhost:8080/health

# SSE endpoints (Memory, Indexer)
curl -sI http://localhost:8000/sse | head -n1
curl -sI http://localhost:8001/sse | head -n1

# RMCP endpoints (HTTP JSON-RPC)
curl -sI http://localhost:8002/mcp | head -n1
curl -sI http://localhost:8003/mcp | head -n1

Expected HTTP Behaviors

• GET /mcp returns 400: Normal - RMCP endpoint is POST-only for JSON-RPC
• SSE requires session handshake: Raw POST /messages without session will error (expected)

Operational Safeguards

Schema repair: ensure_collection repairs missing named vectors (lex, mini when REFRAG_MODE=1) on existing collections.

Debug Logging

export DEBUG_CONTEXT_ANSWER=1
export HYBRID_DEBUG=1
export CACHE_DEBUG=1

# Restart services
docker-compose restart

Getting Help

1. Check this troubleshooting guide
2. Review logs: docker compose logs mcp_indexer
3. Verify health: make health
4. Check Qdrant status: make qdrant-status