Troubleshooting

Common issues and solutions for self-hosted Kortix

Setup Issues

Setup Wizard Fails to Start

Problem: python setup.py crashes or shows dependency errors.

Solution:

1. Check Python Version

   python --version  # Should be 3.11+
   

   If version is too old, install Python 3.11 or newer.

2. Install Dependencies

   pip install pydantic rich
   

   Or use the setup script’s auto-install feature.

3. Try Alternative Command

   python -m setup
   

Docker Not Running

Problem: Setup wizard reports “Docker is not running.”

Solution:

# Start Docker (varies by OS)

# macOS/Windows
# Open Docker Desktop application

# Linux
sudo systemctl start docker

# Verify Docker is running
docker ps

Invalid Supabase Credentials

Problem: Setup completes but authentication fails with “alg value is not allowed.”

Solution:

The JWT secret doesn’t match exactly.

1. Get Correct JWT Secret

   1. Go to Supabase Dashboard → Project Settings → API
   2. Scroll to “JWT Settings”
   3. Copy the JWT Secret exactly (including any special characters)
2. Update Configuration

   python setup.py
   # Select "Add/Update API Keys"
   # Re-enter Supabase credentials
   
3. Restart Services

   python start.py restart
   

Database Connection Fails

Problem: Backend logs show “could not connect to database.”

Solution:

Check Connection String

# Verify DATABASE_URL format
cat backend/.env | grep DATABASE_URL

# Should look like:
# postgresql://postgres.xxx:[e-mail]:6543/postgres

Common issues:

• Wrong password in connection string
• Using Session pooler instead of Transaction pooler (should use port 6543)
• IP restrictions in Supabase (check Project Settings → Database → Network Restrictions)

Service Startup Issues

Services Don’t Start

Problem: python start.py shows services as stopped.

Solution:

Docker Setup

# Check Docker Compose logs
docker compose logs

# Check specific service
docker compose logs backend
docker compose logs frontend

# Restart services
docker compose down
docker compose up -d

Manual Setup

# Check log files
tail -f backend.log
tail -f frontend.log

# Manually start services

# Terminal 1: Redis
docker compose up redis -d

# Terminal 2: Backend
cd backend && uv run api.py

# Terminal 3: Frontend
cd apps/frontend && pnpm run dev

Port Already in Use

Problem: “Address already in use” error for ports 3000 or 8000.

Solution:

# Find process using port 3000
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill process
kill -9 <PID>  # macOS/Linux
taskkill /F /PID <PID>  # Windows

# Or use different ports
# Edit docker-compose.yaml
ports:
  - "3001:3000"  # Frontend
  - "8001:8000"  # Backend

Redis Connection Failed

Problem: Backend can’t connect to Redis.

Solution:

# Check Redis is running
docker compose ps redis

# Start Redis if stopped
docker compose up -d redis

# Test Redis connection
redis-cli ping  # Should return PONG

# Check Redis logs
docker compose logs redis

Runtime Issues

Frontend Shows 502 Bad Gateway

Problem: Frontend loads but shows “502 Bad Gateway” errors.

Solution:

Backend is not running or not reachable.

1. Check Backend Status

   # Test backend directly
   curl http://localhost:8000/v1/health-docker
   
   # Should return: {"status":"healthy"}
   
2. Check Backend Logs

   # Docker
   docker compose logs backend
   
   # Manual
   tail -f backend.log
   
3. Verify Configuration

   Check apps/frontend/.env.local:

   NEXT_PUBLIC_BACKEND_URL=http://localhost:8000/v1
   

Agent Execution Fails

Problem: Agents fail to execute with “Daytona connection error.”

Solution:

1. Verify Daytona API Key

   # Check backend/.env
   cat backend/.env | grep DAYTONA_API_KEY
   
2. Test Daytona Connection

   curl -H "Authorization: Bearer YOUR_DAYTONA_API_KEY" \
     https://app.daytona.io/api/health
   
3. Check Daytona Quota

   Visit app.daytona.io and check your usage limits.

LLM API Errors

Problem: Agents return “LLM API error” or rate limit errors.

Solution:

Rate Limits

You’ve hit API rate limits.

• Check your LLM provider dashboard for limits
• Upgrade to higher tier plan
• Add additional LLM providers as fallbacks

Invalid API Key

# Re-run setup to update keys
python setup.py
# Select "Add/Update API Keys"

# Restart services
python start.py restart

Wrong Model Selected

# Check MAIN_LLM configuration
cat backend/.env | grep MAIN_LLM

# Verify you have the required API key
# For anthropic: ANTHROPIC_API_KEY
# For bedrock: AWS_BEARER_TOKEN_BEDROCK
# For grok/openai/minimax: OPENROUTER_API_KEY

Memory Issues

Problem: Backend crashes with “killed” or out-of-memory errors.

Solution:

Docker

Increase Docker memory limits:

Edit docker-compose.yaml:

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 4G  # Increase from default

Restart:

docker compose down
docker compose up -d

System

Your system doesn’t have enough RAM.

• Close other applications
• Upgrade system RAM
• Use a cloud instance with more memory

Deployment Issues

ECS Task Fails to Start

Problem: ECS tasks fail health checks and restart continuously.

Solution:

1. Check Task Logs

   AWS Console → ECS → Cluster → Service → Logs

   Or via CLI:

   aws logs tail /ecs/suna-backend --follow
   
2. Verify Secrets

   Ensure AWS Secrets Manager has all required environment variables:

   aws secretsmanager get-secret-value \
     --secret-id suna-env-prod \
     --query SecretString
   
3. Check Task Definition

   Verify CPU/memory limits are sufficient:

   • Minimum: 2048 CPU (2 vCPU), 4096 MB
   • Recommended: 4096 CPU (4 vCPU), 8192 MB

EKS Pod CrashLoopBackOff

Problem: Kubernetes pods keep restarting.

Solution:

# Check pod status
kubectl get pods -n suna

# View pod logs
kubectl logs <pod-name> -n suna

# View previous crash logs
kubectl logs <pod-name> -n suna --previous

# Describe pod for events
kubectl describe pod <pod-name> -n suna

Common causes:

• Missing environment variables (sync secrets)
• Insufficient memory (OOMKilled)
• Database connection issues
• Bad container image (rollback)

Fix:

# Sync secrets
kubectl create secret generic suna-env -n suna \
  --from-env-file=secrets.env --dry-run=client -o yaml | kubectl apply -f -

# Rollback bad deployment
kubectl rollout undo deployment/suna-api -n suna

# Restart pods
kubectl rollout restart deployment/suna-api -n suna

Load Balancer Health Check Fails

Problem: ALB shows unhealthy targets.

Solution:

1. Test Health Endpoint

   # From inside pod/container
   curl http://localhost:8000/v1/health-docker
   
   # Should return: {"status":"healthy"}
   
2. Check Health Check Config

   ALB Target Group settings:

   • Path: /v1/health-docker
   • Port: 8000
   • Interval: 30 seconds
   • Timeout: 5 seconds
   • Healthy threshold: 2
   • Unhealthy threshold: 3
3. Verify Security Groups

   Ensure ALB can reach backend on port 8000:

   • Backend security group allows inbound on 8000 from ALB
   • ALB security group allows outbound to backend

Performance Issues

Slow Response Times

Problem: Agents take a long time to respond.

Causes & Solutions:

Cold Start Delays

First request after deployment is slower.

Solution: Increase minimum replicas or keep services warm with health checks.

LLM Provider Latency

Some LLM providers are slower than others.

Solution:

• Use faster models (e.g., Claude Haiku, GPT-4o-mini)
• Switch to providers with better latency in your region
• Enable streaming for real-time responses

Database Queries

Slow Supabase queries.

Solution:

• Check Supabase performance metrics
• Add database indexes
• Upgrade Supabase plan for more resources

Insufficient Resources

Backend running out of CPU/memory.

Solution:

# Check resource usage
docker stats  # Docker
kubectl top pods -n suna  # Kubernetes

# Scale up
kubectl scale deployment/suna-api -n suna --replicas=6

High Memory Usage

Problem: Backend memory usage grows over time.

Solution:

1. Monitor Memory

   # Docker
   docker stats
   
   # Kubernetes
   kubectl top pods -n suna
   
2. Enable Auto-Scaling

   For Kubernetes:

   # HPA scales based on memory
   kubectl get hpa -n suna
   

   For Docker Compose:

   # Periodic restart (cron job)
   0 */6 * * * cd /path/to/suna && docker compose restart backend
   
3. Increase Memory Limits

   Temporarily increase limits while investigating:

   Docker Compose:

   services:
     backend:
       deploy:
         resources:
           limits:
             memory: 6G
   

   Kubernetes:

   resources:
     limits:
       memory: 4Gi
   

Data Issues

Lost Conversations

Problem: Chat history disappears.

Solution:

Check Supabase connection and data:

# Connect to Supabase database
psql "$DATABASE_URL"

# Check threads table
SELECT COUNT(*) FROM threads;

# Check messages table
SELECT COUNT(*) FROM messages;

Common causes:

• Supabase project paused (free tier inactivity)
• Database connection issues
• User authentication issues

File Upload Failures

Problem: Can’t upload files to agents.

Solution:

1. Check Supabase Storage

   Supabase Dashboard → Storage → Policies

   Ensure storage policies allow authenticated uploads.

2. Check File Size Limits

   Default limits:

   • Supabase: 50MB per file
   • Backend: Configurable in environment
3. Verify CORS Settings

   Supabase Dashboard → Storage → Settings

   Add your frontend URL to allowed origins.

Debugging Tools

Logs

Docker Compose

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend

# Last 100 lines
docker compose logs --tail=100 backend

Manual Setup

# Backend logs
tail -f backend.log

# Frontend logs
tail -f frontend.log

# Both
tail -f backend.log frontend.log

Kubernetes

# All pods
kubectl logs -l app.kubernetes.io/name=suna-api -n suna -f

# Specific pod
kubectl logs <pod-name> -n suna -f

# Previous crash
kubectl logs <pod-name> -n suna --previous

Health Checks

# Backend health
curl http://localhost:8000/v1/health-docker

# Frontend (should return HTML)
curl http://localhost:3000

# Redis
redis-cli ping

# Supabase
curl https://your-project.supabase.co/rest/v1/

Database Inspection

# Connect to database
psql "$DATABASE_URL"

# List tables
\dt

# Check users
SELECT id, email, created_at FROM auth.users;

# Check agents
SELECT id, name, created_at FROM agents;

# Check threads
SELECT id, title, created_at FROM threads ORDER BY created_at DESC LIMIT 10;

Getting Help

If you’re still stuck:

Discord Community

Get real-time help from the community

GitHub Issues

Report bugs and request features

Documentation

Review setup and configuration guides

GitHub Discussions

Ask questions and share solutions

Common Error Messages

Error	Cause	Solution
alg value is not allowed	JWT secret mismatch	Re-enter exact JWT secret from Supabase
connection refused	Service not running	Start services with python start.py
OOMKilled	Out of memory	Increase memory limits or scale horizontally
CrashLoopBackOff	Pod keeps crashing	Check logs with kubectl logs
502 Bad Gateway	Backend unreachable	Verify backend is running and accessible
Database connection failed	Wrong DATABASE_URL	Check connection string format
API key invalid	Wrong/expired API key	Update API key in configuration
Rate limit exceeded	Too many API calls	Upgrade LLM provider plan or add fallbacks

For detailed troubleshooting of specific deployment types, see the EKS Operations Guide.