Troubleshooting the reasoning service

Diagnose and resolve common issues with the reasoning service, including initialization failures, runtime errors, and performance problems.

The reasoning service is a critical component of Content Cortex AI Services that orchestrates interactions between the AI Agent plug-in, MCP servers, and Large Language Models. When issues occur, they typically fall into two categories: initialization problems that prevent the service from starting, and runtime issues that occur during operation.

Troubleshooting approach

When troubleshooting reasoning service issues:

  • Check container logs for error messages and stack traces
  • Verify configuration files are present and contain valid JSON
  • Confirm network connectivity to LLM providers and MCP servers
  • Review authentication credentials and permissions
  • Monitor resource usage (CPU, memory, network)
  • Test connectivity to external services independently

Common issue categories

Reasoning service issues typically fall into these categories:

Initialization issues
Problems that prevent the service from starting, including configuration errors, missing dependencies, connection failures to LLM providers or MCP servers, and resource constraints.
Runtime issues
Problems that occur during operation, including token budget exceeded errors, iteration limit issues, LLM API errors, MCP tool failures, and performance degradation.

Diagnostic tools

Use these tools and commands to diagnose reasoning service issues:

  • View container logs
    kubectl logs <pod-name> -c reasoning-service
  • Check pod status and events
    kubectl describe pod <pod-name>
  • Monitor resource usage
    kubectl top pod <pod-name>
  • Access container for debugging
    kubectl exec -it <pod-name> -- /bin/bash
  • Review reasoning service logs at INFO or DEBUG level for detailed diagnostics

Getting help

If you cannot resolve an issue using the troubleshooting topics, gather the following information before contacting support:

  • Complete container logs from the reasoning service
  • Configuration files (with sensitive information redacted)
  • Description of the issue and steps to reproduce
  • Environment details (Kubernetes version, cluster configuration)
  • Recent changes to configuration or deployment