Troubleshooting

Solutions to the most common problems with self-hosted Tambo.

Services won't start

1. Check Docker is running: docker info
2. Check docker.env exists and has all required variables
3. View logs: ./scripts/cloud/tambo-logs.sh

Database connection errors

1. Verify PostgreSQL is healthy:

   docker compose --env-file docker.env ps postgres

2. Check DATABASE_URL is correctly set (auto-derived from POSTGRES_* variables)

OAuth not working

1. Verify NEXTAUTH_URL matches your deployment URL exactly (no trailing slash)
2. Check OAuth callback URLs in provider settings match your deployment
3. Ensure both _CLIENT_ID and _CLIENT_SECRET are set for the provider

Full reset

Stop and remove all containers and volumes, then start fresh:

# Stop and remove containers + volumes
docker compose --env-file docker.env down -v
docker volume rm tambo_tambo_postgres_data

# Start fresh
./scripts/cloud/tambo-start.sh
./scripts/cloud/init-database.sh