docs/resources/troubleshooting.md

---
title: Troubleshooting
description: Comprehensive troubleshooting guide for KGraph-MCP issues and solutions
---

# Troubleshooting

Common issues, solutions, and debugging guides for KGraph-MCP development and deployment.

## 🚨 Common Issues {#common-issues}

### **Installation Issues**

#### Python Version Compatibility
```bash
# Error: Python version not supported
# Solution: Install Python 3.11.8+
just setup  # Automatically installs correct Python version
```

#### Package Installation Failures
```bash
# Error: Failed to install dependencies
# Solution: Clear cache and reinstall
just clean-all
just setup
```

#### Permission Errors
```bash
# Error: Permission denied during setup
# Solution: Check file permissions
chmod +x justfile
sudo chown -R $USER:$USER .
```

### **Development Issues**

#### Import Errors
```bash
# Error: ModuleNotFoundError
# Solution: Ensure virtual environment is activated
source .venv/bin/activate
just install  # Reinstall dependencies
```

#### Type Checking Failures
```bash
# Error: mypy type checking failed
# Solution: Fix type annotations
just type-check  # See specific errors
```

#### Linting Errors
```bash
# Error: Ruff linting failed
# Solution: Auto-fix most issues
just lint  # Automatically fixes issues
just format  # Format code
```

### **Documentation Issues**

#### MkDocs Build Failures
```bash
# Error: MkDocs build failed
# Solution: Validate and fix configuration
just docs-validate  # Check for issues
just docs-serve     # Test locally
```

#### Missing Dependencies
```bash
# Error: Plugin not found
# Solution: Install documentation dependencies
uv pip install -r requirements-dev.txt
```

#### Broken Links
```bash
# Error: Link validation failed
# Solution: Check and fix internal links
# Use relative paths: ../section/page.md
```

## 🔧 **Development Environment Issues**

### **Virtual Environment Problems**

#### Environment Not Found
```bash
# Recreate virtual environment
rm -rf .venv
just setup
```

#### Package Conflicts
```bash
# Clear and reinstall all packages
just clean
just update
```

### **Git Issues**

#### Pre-commit Failures
```bash
# Fix pre-commit issues
just pre-commit  # Run checks
git add .        # Stage fixes
git commit -m "fix: resolve pre-commit issues"
```

#### Branch Management
```bash
# Clean up merged branches
just branch-cleanup
```

## 🌐 **Application Issues**

### **Server Startup Problems**

#### Port Already in Use
```bash
# Error: Port 8000 already in use
# Solution: Kill existing process or use different port
lsof -ti:8000 | xargs kill -9
# Or specify different port
uvicorn app:app --port 8001
```

#### Missing Environment Variables
```bash
# Create .env file from template
cp .env.example .env
# Edit .env with your configurations
```

### **Gradio Interface Issues**

#### UI Not Loading
```bash
# Check if server is running
curl http://localhost:7860
# Restart application
just dev
```

#### WebSocket Errors
```bash
# Clear browser cache and reload
# Check firewall settings
# Ensure port 7860 is accessible
```

## 📊 **Performance Issues**

### **Slow Response Times**

#### Database Performance
```bash
# Check database connections
# Monitor query performance
just stats  # View system statistics
```

#### Memory Usage
```bash
# Monitor memory usage
just profile-memory
# Or use system monitor
top -p $(pgrep -f "python app.py")
```

### **High CPU Usage**
```bash
# Profile CPU usage
just monitor
# Check for infinite loops or heavy computations
```

## 🔍 **Debugging Techniques**

### **Enable Debug Logging**
```python
# Add to app.py
import logging
logging.basicConfig(level=logging.DEBUG)
```

### **Use Development Mode**
```bash
# Run with debug enabled
APP_ENV=development just dev
```

### **Test Individual Components**
```bash
# Test specific functionality
just test-file tests/test_specific.py
```

## 📋 **Error Messages & Solutions**

### **Common Error Patterns**

| Error Pattern | Likely Cause | Solution |
|---------------|--------------|----------|
| `ModuleNotFoundError` | Missing package or wrong Python path | `just install` |
| `Permission denied` | File permission issues | `chmod +x` or `sudo chown` |
| `Port already in use` | Another process using port | Kill process or use different port |
| `Connection refused` | Server not running | Start server with `just dev` |
| `Import error` | Virtual environment not activated | `source .venv/bin/activate` |

### **System Requirements Check**
```bash
# Verify system requirements
python --version   # Should be 3.11.8+
node --version     # Should be 16+
git --version      # Should be 2.0+
```

## 🆘 **Getting Help**

### **Self-Help Resources**
1. Check this troubleshooting guide
2. Review the [FAQ](faq.md)
3. Search existing [GitHub Issues](https://github.com/BasalGanglia/kgraph-mcp-hackathon/issues)
4. Check the [Developer Guide](../developer-guide/index.md)

### **Community Support**
- **GitHub Issues**: [Report bugs and request features](https://github.com/BasalGanglia/kgraph-mcp-hackathon/issues/new)
- **Discussions**: [GitHub Discussions](https://github.com/BasalGanglia/kgraph-mcp-hackathon/discussions)

### **Information to Include**
When reporting issues, please include:
- Operating system and version
- Python version (`python --version`)
- Error messages (full stack trace)
- Steps to reproduce
- Expected vs actual behavior

## 🔗 **Related Resources**

- [Installation Guide](../user-guide/installation.md) - Setup instructions
- [Developer Guide](../developer-guide/index.md) - Development setup
- [API Reference](../api/index.md) - API documentation
- [FAQ](faq.md) - Frequently asked questions

---

*This page is part of the [Resources](index.md) documentation section.*