Troubleshooting Guide

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

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:

Check Logs: Enable debug logging with LOG_LEVEL=DEBUG
Review Documentation: See our comprehensive docs
Search Issues: Check GitHub Issues
Ask Community: Post in GitHub Discussions
Report Bug: Create an issue with:
- Error message
- Steps to reproduce
- Environment details (python --version, kubectl version, etc.)
- Relevant logs