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_ids 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_ids 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.