Use the following guidance that provides targeted troubleshooting steps for common debugging scenarios.

Per-tool context missing

Perform the following checks to ensure per-tool context is correctly configured. Missing context can prevent proper enrichment and visibility during debugging. For more information about managing per-tool context, see Manage per-tool context.

  1. Confirm that the context/ directory exists in the container.
  2. Verify that per_tool_context_enabled is not set to false.
  3. Ensure files are named using the <operationId>.md or <operationId>.txt format.
  4. Enable openapi_logging.annotations and restart the service.

Large responses trimmed or blocked

Perform the following steps to verify and adjust response guard settings when large responses are trimmed or blocked. These limits help prevent excessive payload sizes but may need adjustment for certain operations.
  1. Verify the mode in the logs. The mode can be block, trim, or warn.
  2. Inspect the runtime.http.response_guard configuration to confirm current limits.
  3. Increase max_items and max_bytes values incrementally to avoid excessive payloads.

Resolve tool invocation errors

During tool invocation, errors can result from incorrect request handling, parameter validation issues, or downstream header misconfigurations. Perform the following checks to diagnose and resolve tool invocation errors:
  1. Turn on structured logging to capture request IDs for correlation.
  2. Match the errors logger stack trace with the corresponding audit event for detailed context.
  3. If parameter validation is enabled, review the tools.validation logs for errors.
  4. Set logging.loggers.http.config=DEBUG to confirm that default_headers are resolved correctly and that the Authorization header is preserved.
  5. For repeated "Invalid params" errors (JSON-RPC -32602) without enabling global DEBUG, set runtime.middleware.validation_diagnostics.enabled=true and check validation.diagnostics logs for method names and argument key lists.

Resolve authentication and token exchange issues

Problems related to authentication and token exchange often involve token expiry or parsing errors. The following configuration settings help you enable targeted debugging without exposing sensitive information:
Setting Purpose
auth.token_exchange=DEBUG Enables detailed logs for token exchange operations
auth.verify=DEBUG Provides visibility into token verification steps

Diagnose rate limiting denials

Rate limiting denials occur when requests exceed the configured threshold. Audit events provide visibility into these occurrences. Use the following steps to verify rate limiting denials and adjust configuration settings:
  • Check audit events—Look for entries where "category":"rate_limit" appears in the logs.
  • Tune request limits—Adjust the max_requests_per_second setting to align with expected traffic patterns.

Debug TLS and mTLS issues

Enabling detailed logging for TLS and mTLS operations help diagnose certificate loading and hostname verification problems during secure communication. Enable the http.tls=DEBUG setting to display certificate and key loading details and hostname verification decisions.