Installation Issues

Troubleshooting guide for installation and dependency issues with MCP Server with LangGraph

Installation Issues

This guide covers common installation problems and their solutions.

Python Version Mismatch

Symptom: ERROR: This package requires Python >=3.10,<3.13

Solution:

# Check your Python version
python --version

# If using pyenv, install correct version
pyenv install 3.12.7
pyenv local 3.12.7

# Recreate virtual environment
rm -rf .venv
python -m venv .venv
source .venv/bin/activate

---

uv Lock File Out of Sync

Symptom: ERROR: uv.lock out of sync with pyproject.toml

Solution:

# Regenerate lock file
uv lock

# Install dependencies
uv sync

# For development extras
uv sync --extra dev

---

Missing Optional Dependencies

Symptom: ModuleNotFoundError: No module named 'google.cloud'

Solution:

# Install specific extras
uv sync --extra gcp          # For Google Cloud
uv sync --extra aws          # For AWS
uv sync --extra secrets      # For Infisical
uv sync --extra code-execution  # For code execution

# Install all extras
uv sync --all-extras

---

Conflicting Dependencies

Symptom: ERROR: Cannot install X and Y because these package versions have conflicting dependencies

Solution:

# Clear uv cache
uv cache clean

# Remove lock file and regenerate
rm uv.lock
uv lock

# If issue persists, check pyproject.toml for version constraints
# Look for overly restrictive version pins like ==1.2.3
# Consider changing to >=1.2.3,<2.0.0

---

Pre-commit Hook Failures

Symptom: Pre-commit hooks fail during installation or first run

Solution:

# Clean pre-commit cache
pre-commit clean

# Reinstall hooks
pre-commit install --install-hooks

# Run manually to check
pre-commit run --all-files

---

Virtual Environment Issues

Symptom: Command 'python' not found or wrong Python version in venv

Solution:

# Remove existing venv
rm -rf .venv

# Create with specific Python version
python3.12 -m venv .venv

# Activate
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Verify version
python --version

---

Docker Build Failures During Install

Symptom: Docker build fails at dependency installation step

Common Causes & Solutions:

1. Base Image Issue

# Use specific SHA instead of tag
FROM python:3.12-slim@sha256:abc123...

# Or use stable tag
FROM python:3.12.7-slim

2. Missing System Dependencies

# Add system dependencies before Python packages
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

3. Cache Invalidation

# Copy only requirements first for better caching
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen

# Then copy source code
COPY . .

---

Still Having Issues?

If you’re still experiencing installation problems:

1. Check Prerequisites: Ensure you have Python 3.10-3.12, uv, and git installed
2. Review Documentation: See our installation guide
3. Search Issues: Check GitHub Issues
4. Ask Community: Post in GitHub Discussions