> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Comprehensive troubleshooting guide for common issues with MCP Server with LangGraph

# Troubleshooting Guide

This guide provides solutions to common issues encountered when working with MCP Server with LangGraph.

## Quick Navigation

<CardGroup cols={2}>
  <Card title="Installation Issues" icon="download" href="/troubleshooting/installation">
    Dependency conflicts, Python version mismatches, package errors
  </Card>

  <Card title="Deployment Problems" icon="rocket" href="/troubleshooting/deployment">
    Kubernetes, Docker, Cloud Run deployment failures
  </Card>

  <Card title="Authentication Issues" icon="shield" href="/troubleshooting/authentication">
    JWT errors, Keycloak problems, OpenFGA authorization
  </Card>

  <Card title="Performance Problems" icon="gauge" href="/troubleshooting/performance">
    Slow responses, memory leaks, connection timeouts
  </Card>

  <Card title="CI/CD Failures" icon="code-branch" href="/troubleshooting/ci-cd">
    GitHub Actions errors, test failures, build problems
  </Card>

  <Card title="Database Issues" icon="database" href="/troubleshooting/database">
    Redis connection errors, PostgreSQL problems, session storage
  </Card>
</CardGroup>

***

## Kubernetes-Specific Guides

<CardGroup cols={2}>
  <Card title="Pod Failures" icon="cube" href="/troubleshooting/pod-failures">
    CrashLoopBackOff, ImagePullBackOff, pending pods, GKE Autopilot issues
  </Card>

  <Card title="GKE Runbooks" icon="book" href="/deployment/operations/gke-runbooks">
    GKE-specific troubleshooting and operational procedures
  </Card>

  <Card title="EKS Runbooks" icon="book" href="/deployment/operations/eks-runbooks">
    AWS EKS troubleshooting and operational procedures
  </Card>

  <Card title="Advanced Troubleshooting" icon="microscope" href="/advanced/troubleshooting">
    Deep-dive debugging techniques
  </Card>
</CardGroup>

***

## Quick Diagnostic Commands

### Check Service Health

```bash theme={null}
# Local development
curl http://localhost:8000/health

# Kubernetes
kubectl get pods -n mcp-server
kubectl logs -n mcp-server <pod-name>
```

### Enable Debug Logging

```bash theme={null}
# Set environment variable
export LOG_LEVEL=DEBUG

# Or in .env file
LOG_LEVEL=DEBUG
```

### View Traces

```bash theme={null}
# Open LangSmith dashboard (if configured)
open https://smith.langchain.com

# Or check local Jaeger
open http://localhost:16686
```

***

## Common Quick Fixes

| Issue                     | Quick Fix                                   |
| ------------------------- | ------------------------------------------- |
| `ModuleNotFoundError`     | `uv sync --extra dev`                       |
| Pod `CrashLoopBackOff`    | Check logs: `kubectl logs <pod> --previous` |
| `401 Unauthorized`        | Verify JWT token is valid and not expired   |
| `503 Service Unavailable` | Check upstream service health               |
| `OOM Killed`              | Increase memory limits in deployment        |
| Tests fail in CI          | Ensure `uv sync --extra dev` in workflow    |

***

## Getting More Help

If you're still experiencing issues:

1. **Check Logs**: Enable debug logging with `LOG_LEVEL=DEBUG`
2. **Review Documentation**: See our [comprehensive docs](/getting-started/introduction)
3. **Search Issues**: Check [GitHub Issues](https://github.com/vishnu2kmohan/mcp-server-langgraph/issues)
4. **Ask Community**: Post in [GitHub Discussions](https://github.com/vishnu2kmohan/mcp-server-langgraph/discussions)
5. **Report Bug**: [Create an issue](https://github.com/vishnu2kmohan/mcp-server-langgraph/issues/new) with:
   * Error message
   * Steps to reproduce
   * Environment details (`python --version`, `kubectl version`, etc.)
   * Relevant logs

***

## Troubleshooting Guides Index

| Guide                                             | Description                   |
| ------------------------------------------------- | ----------------------------- |
| [Installation](/troubleshooting/installation)     | Python, uv, dependencies      |
| [Deployment](/troubleshooting/deployment)         | Kubernetes, Docker, Cloud Run |
| [Authentication](/troubleshooting/authentication) | JWT, Keycloak, OpenFGA        |
| [Performance](/troubleshooting/performance)       | Memory, CPU, latency          |
| [CI/CD](/troubleshooting/ci-cd)                   | GitHub Actions, builds, tests |
| [Database](/troubleshooting/database)             | PostgreSQL, Redis, sessions   |
| [Pod Failures](/troubleshooting/pod-failures)     | Kubernetes pod issues         |