Troubleshooting

Setup Issues

Setup Wizard Fails to Start

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

Check Python Version

python --version  # Should be 3.11+

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

Install Dependencies

pip install pydantic rich

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

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.

Get Correct JWT Secret

Go to Supabase Dashboard → Project Settings → API
Scroll to “JWT Settings”
Copy the JWT Secret exactly (including any special characters)

Update Configuration

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

Restart Services

python start.py restart

Database Connection Fails

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

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

# Should look like:
# postgresql://postgres.xxx:[email protected]: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
Manual 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

# 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.

Check Backend Status

# Test backend directly
curl http://localhost:8000/v1/health-docker

# Should return: {"status":"healthy"}

Check Backend Logs

# Docker
docker compose logs backend

# Manual
tail -f backend.log

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:

Verify Daytona API Key

# Check backend/.env
cat backend/.env | grep DAYTONA_API_KEY

Test Daytona Connection

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

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
Invalid API Key
Wrong Model Selected

You’ve hit API rate limits.

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

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

# Restart services
python start.py restart

# 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
System

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

Deployment Issues

ECS Task Fails to Start

Problem: ECS tasks fail health checks and restart continuously. Solution:

Check Task Logs

AWS Console → ECS → Cluster → Service → LogsOr via CLI:

aws logs tail /ecs/suna-backend --follow

Verify Secrets

Ensure AWS Secrets Manager has all required environment variables:

aws secretsmanager get-secret-value \
  --secret-id suna-env-prod \
  --query SecretString

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:

Test Health Endpoint

# From inside pod/container
curl http://localhost:8000/v1/health-docker

# Should return: {"status":"healthy"}

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

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:

Monitor Memory

# Docker
docker stats

# Kubernetes
kubectl top pods -n suna

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

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:

Check Supabase Storage

Supabase Dashboard → Storage → PoliciesEnsure storage policies allow authenticated uploads.

Check File Size Limits

Default limits:

Supabase: 50MB per file
Backend: Configurable in environment

Verify CORS Settings

Supabase Dashboard → Storage → SettingsAdd your frontend URL to allowed origins.

Debugging Tools

Logs

Docker Compose
Manual Setup
Kubernetes

# 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

# Backend logs
tail -f backend.log

# Frontend logs
tail -f frontend.log

# Both
tail -f backend.log frontend.log

# 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.

Get Started

Core Concepts

Building Agents

Agent Capabilities

Tools & Extensions

Platform Features

Self-Hosting

​Setup Issues

​Setup Wizard Fails to Start

​Docker Not Running

​Invalid Supabase Credentials

​Database Connection Fails

​Service Startup Issues

​Services Don’t Start

​Port Already in Use

​Redis Connection Failed

​Runtime Issues

​Frontend Shows 502 Bad Gateway

​Agent Execution Fails

​LLM API Errors

​Memory Issues

​Deployment Issues

​ECS Task Fails to Start

​EKS Pod CrashLoopBackOff

​Load Balancer Health Check Fails

​Performance Issues

​Slow Response Times

​High Memory Usage

​Data Issues

​Lost Conversations

​File Upload Failures

​Debugging Tools

​Logs

​Health Checks

​Database Inspection

​Getting Help

Discord Community

GitHub Issues

Documentation

GitHub Discussions

​Common Error Messages

Build docs developers (and LLMs) love

Setup Issues

Setup Wizard Fails to Start

Docker Not Running

Invalid Supabase Credentials

Database Connection Fails

Service Startup Issues

Services Don’t Start

Port Already in Use

Redis Connection Failed

Runtime Issues

Frontend Shows 502 Bad Gateway

Agent Execution Fails

LLM API Errors

Memory Issues

Deployment Issues

ECS Task Fails to Start

EKS Pod CrashLoopBackOff

Load Balancer Health Check Fails

Performance Issues

Slow Response Times

High Memory Usage

Data Issues

Lost Conversations

File Upload Failures

Debugging Tools

Logs

Health Checks

Database Inspection

Getting Help

Common Error Messages