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

Installation Issues

Dependency conflicts, Python version mismatches, package errors

Deployment Problems

Kubernetes, Docker, Cloud Run deployment failures

Authentication Issues

JWT errors, Keycloak problems, OpenFGA authorization

Performance Problems

Slow responses, memory leaks, connection timeouts

CI/CD Failures

GitHub Actions errors, test failures, build problems

Database Issues

Redis connection errors, PostgreSQL problems, session storage

---

Kubernetes-Specific Guides

Pod Failures

CrashLoopBackOff, ImagePullBackOff, pending pods, GKE Autopilot issues

GKE Runbooks

GKE-specific troubleshooting and operational procedures

EKS Runbooks

AWS EKS troubleshooting and operational procedures

Advanced Troubleshooting

Deep-dive debugging techniques

---

Quick Diagnostic Commands

Check Service Health

# Local development
curl http://localhost:8000/health

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

Enable Debug Logging

# Set environment variable
export LOG_LEVEL=DEBUG

# Or in .env file
LOG_LEVEL=DEBUG

View Traces

# 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
3. Search Issues: Check GitHub Issues
4. Ask Community: Post in GitHub Discussions
5. Report Bug: Create an issue with:
   • Error message
   • Steps to reproduce
   • Environment details (python --version, kubectl version, etc.)
   • Relevant logs

---

Troubleshooting Guides Index

Guide	Description
Installation	Python, uv, dependencies
Deployment	Kubernetes, Docker, Cloud Run
Authentication	JWT, Keycloak, OpenFGA
Performance	Memory, CPU, latency
CI/CD	GitHub Actions, builds, tests
Database	PostgreSQL, Redis, sessions
Pod Failures	Kubernetes pod issues