Orchestrator/bahn/teamlandkarte-mcp/docs/troubleshooting.md

# Troubleshooting

## The server fails at startup with `Missing config.toml`

- Copy the template and fill in non-secret settings:
  - `cp config.toml.example config.toml`
- Ensure `--config` points to the correct file when starting the server.

## Database connectivity problems

Symptoms:

- `DatabaseError: Trino error: ...`

Checklist:

1. Verify host/port in `config.toml`.
2. Verify username/password.
3. Verify TLS settings: `http_scheme` and `verify_ssl`.
4. Ensure `database.backend = "trino"`.
5. Run the smoke check script: `scripts/trino_smoke_check.py`.

## Confirmation gate blocks matching

Symptoms:

- A matching tool refuses to run and tells you to confirm requirements.

Explanation:

- Requirement capture tools write **pending** requirements.
- When `matching.require_confirmation = true` (default), matching tools require an explicit user confirmation flow.

Additional note (multi-client environments):

- Pending/confirmed state is stored in an in-memory server session.
- If multiple clients share one server process, confirmation state can become
  ambiguous. In such setups, enforce the confirmation workflow strictly on the
  client/agent side.

Fix (recommended sequence):

1. Capture/update requirements (e.g. `extract_requirements`, `collect_structured_requirement_data`, `update_requirements`, guided tools).
2. Call `show_pending_requirements()` (review table) **after the last update**.
3. Ask the user to confirm (Yes/No).
4. Call `confirm_requirements(confirm=true)`.
5. Re-run the matching tool.

Optional (dev/testing):

- Set `matching.require_confirmation = false` in `config.toml` to auto-skip confirmation.

## confirm_requirements was called but matching is still blocked

Symptoms:

- The assistant called `confirm_requirements(confirm=true)` but matching tools still refuse to run.

Explanation:

- The workflow is two-step: the assistant must first request user confirmation.
- The recommended sequence is:
  1. `show_pending_requirements()` (review table)
  2. Ask the user to confirm (Yes/No)
  3. `confirm_requirements(confirm=true)`

Fix:

- If requirements were updated after the review step, you must re-run `show_pending_requirements()` and ask the user again.
- Then call `confirm_requirements(confirm=true)`.

## Guided capture feels stuck

Guided capture is step-based. Call the tools in order:

1. `start_guided_capture()`
2. `guided_set_description(...)`
3. `guided_set_role(...)`
4. `guided_set_time_range(date_start?, date_end?)` (open-ended ranges are allowed)
5. `guided_set_competences([...])`
6. `show_pending_requirements()`
7. Ask the user to confirm (Yes/No)
8. `confirm_requirements(confirm=true)`

## "Unknown or expired search_id" (or filters/pagination stop working)

Symptoms:

- `get_results_by_category(...)` or `filter_search_results(...)` returns an error.
- Newer server versions also return a machine-readable status:
  - `META.status=unknown_or_expired`

Common causes:

1. **TTL expiry**: the search results cache is time-limited.
   - Controlled by `cache.search_ttl_minutes`.
2. **Eviction due to cache size**: the cache is LRU and bound by `cache.max_size`.
   - If many searches are started, older `search_id`s can be evicted even within TTL.
3. **Process mismatch / restart**: in-memory caches are per server process.
   - If the server restarts, or the client routes to a different instance, old `search_id`s are not available.
4. **Copy hygiene**: some chat UIs add backticks or whitespace.
   - Prefer copying the UUID from the tool output header line `SEARCH_ID=<uuid>`.
   - Do not include backticks, quotes, or extra whitespace.

Fix:

- Re-run the matching tool to create a new `search_id`.
- Increase `cache.search_ttl_minutes` and/or `cache.max_size` for longer interactive sessions.
- Ensure your MCP client uses a single long-lived server process.

## "Invalid search_id format (expected UUID)"

Cause:

- The server validates `search_id` inputs and rejects anything that is not a UUID.

Fix:

- Copy the value from the most recent tool output header:
  - `Using SEARCH_ID=<uuid>` (first line)
  - or `SEARCH_ID=<uuid>`

## Search tool output parsing (Cherry Studio / chat UI issues)

Search-related tools emit deterministic headers (intended to be parsed verbatim):

- First line marker:
  - `Using SEARCH_ID=<uuid>`
- Machine-readable headers:
  - `SEARCH_ID=<uuid>`
  - `FILTER_ID=<uuid>` (if applicable)
  - `META=<json>`

Output shape notes:

- Only `find_matching_capacities` includes the category-count `## Summary` table.
- `filter_search_results` includes an **Applied Filters** table and a flat results table with a `Category` column (it does not reprint the summary counts).
- `get_results_by_category` returns a single category-page table (it does not reprint the summary counts).

If your UI hides tool output:

- Re-run the tool call, or
- manually copy the UUID from the server output and paste it without formatting.

## "No matches" or unexpectedly few matches

- Confirm the required competences list is not over-specific.
- Confirm role name is reasonable (role similarity affects scoring).
- If you supplied date filters, remember availability is filter-only:
  - capacities must overlap the requested range
  - open-ended capacity `end_date` is treated as available without limit

## Debug logging

Start the server with:

- `--log-level DEBUG`

The database clients emit safe query logs (SQL is normalized; parameters are redacted).

## Cherry Studio: stdio "connection closed" / tools not listing

Common causes:

- The server writes logs to stdout (breaks JSON-RPC). This project logs to
  **stderr**.
- Cherry cannot set a working directory, so `uv run` cannot find the project.

Workaround (wrap with `zsh -lc`):

- `zsh -lc 'cd /Users/thomashandke/ws/teamlandkarte-mcp && uv run python -m teamlandkarte_mcp --config /Users/thomashandke/ws/teamlandkarte-mcp/config.toml --log-level DEBUG'`

Also ensure your `PATH` contains your `uv`/`uvx` directory, e.g.
`/Users/thomashandke/.local/bin`.

## Azure OpenAI API Errors

Symptoms:

- Tools that compute similarity fail with `AzureAPIError`.

Common causes and fixes:

1. **Missing credentials**
   - Ensure the environment variable is set:
     - `AZURE_OPENAI_EMBEDDING_API_KEY`
   - If you rely on `.env`, confirm it is loaded in the shell that starts the MCP
     server.

2. **Invalid endpoint / deployment**
   - Check `[azure_openai].endpoint` in `config.toml` (must be your Azure OpenAI
     resource endpoint).
   - Check `embedding_deployment` exists in Azure and matches your deployment.

3. **Rate limits / throttling (HTTP 429)**
   - Retry later.
   - Reduce concurrency in the client/agent.
   - Use the embedding cache to reduce repeated embedding calls.

4. **Network / TLS / proxy issues**
   - Try `curl` to the Azure endpoint from the same host.
   - If you are behind a corporate proxy, ensure the environment is configured
     accordingly.

Debugging tips:

- Start the server with `--log-level DEBUG` and look at stderr logs.
- Confirm your `config.toml` is the one the server loads (`--config ...`).

## MCP sampling / embedding features

This server uses **Azure OpenAI embeddings** for embedding-based similarity
scoring.

- Ensure `AZURE_OPENAI_EMBEDDING_API_KEY` is set.
- Ensure `[azure_openai]` in `config.toml` points to a valid Azure OpenAI endpoint.

## IDE shows "line too long (.. > 79)" but Ruff passes

Some editor integrations (or their default settings) may enforce a 79 character
line length even if the repository uses a different limit.

If `uv run ruff check` passes but the editor still flags lines:

- Prefer the repo result as the source of truth.
- Adjust your editor/extension settings (Python/Ruff/Flake8) to match the
  project configuration.