# Troubleshooting Guide - MCP Server
## Common Issues & Solutions
### 1. Railway Deployment Failures
#### Issue: App crashes on startup
**Symptoms:**
- Build succeeds but container fails
- Logs show "Application startup complete" then immediate exit
- Return code: 1
**Solution:**
- Check Railway.toml configuration
- Verify correct build/start commands
- Ensure all environment variables set
#### Issue: Database connection errors
**Symptoms:**
```
psycopg2.OperationalError: connection to server at "2600:1f18:2e13:9d29:4c59:7653:3be4:7f3c" failed: Network is unreachable
```
**Solution:**
- Use Supabase Transaction Pooler URL instead of direct connection
- Format: `postgresql://postgres.shcaibujeuinmitesicz:password@aws-1-us-east-1.pooler.supabase.com:6543/postgres`
#### Issue: "Tenant or user not found" error
**Solution:**
- Use correct pooler username format: `postgres.shcaibujeuinmitesicz`
- Not just `postgres`
### 2. Database Connectivity
#### Issue: Redis connection fails
**Symptoms:** App starts but Redis warnings in logs
**Impact:** Limited session/caching functionality
**Status:** Non-critical - app continues running
**Solution:**
- Ensure Redis URL in environment variables
- Consider Redis add-on in Railway
#### Issue: Database auth failures
**Solution:**
1. Verify password in Railway environment variables
2. Check Supabase project status (not paused)
3. Use correct pooler URL format
### 3. Application Logic Errors
#### Issue: MCP endpoints not responding
**Diagnosis:**
- Check if app started properly (GET /health)
- Verify MCP router registration in src/main.py
- Check authentication middleware
**Logs to Monitor:**
```
INFO: Started server process [1]
INFO: Waiting for application startup
INFO:src.main:Starting up application...
INFO:src.main:Database initialized (if successful)
INFO:src.main:Redis connection established (if successful)
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080
```
## Diagnostic Commands
### Check App Status
```bash
curl https://[railway-url].railway.app/health
```
### View Recent Logs
```bash
railway logs --tail 50
```
### Test Database Connection
```bash
# Railway shell
python -c "
import sqlalchemy
from sqlalchemy import create_engine
import os
DATABASE_URL = os.getenv('DATABASE_URL')
try:
engine = create_engine(DATABASE_URL)
connection = engine.connect()
print('Database connection successful')
except Exception as e:
print(f'Database error: {e}')
"
```
## Environment Setup Verification
### Required Railway Variables
- `DATABASE_URL` (Supabase Transaction Pooler)
- `REDIS_URL` (Railway provides)
- `PORT` (8080, Railway default)
### Optional Variables
- `LOG_LEVEL` (info, debug, etc.)
- Custom environment configurations
## Performance Optimization
### Database Connection Pooling
- Use Transaction Pooler (port 6543) not direct connection
- Optimized for server environments like Railway
- Better connection management
### Application Startup
- Implemented graceful error handling
- Optional service dependencies (database, Redis)
- Fast startup with minimal dependencies
