Documentation Index Fetch the complete documentation index at: https://mintlify.com/twentyhq/twenty/llms.txt
Use this file to discover all available pages before exploring further.
Resolve common issues when self-hosting Twenty and learn debugging techniques.
Connection Issues Database Connection Failed Symptoms:
Server fails to start
Error: ECONNREFUSED or could not connect to server
Solutions:
Verify PostgreSQL is running
# Check if PostgreSQL is accessible pg_isready -h localhost -p 5432 # Docker Compose docker compose ps db docker compose logs db # Kubernetes kubectl get pods -n twenty -l app=twenty-postgres kubectl logs -n twenty -l app=twenty-postgres
Verify your PG_DATABASE_URL format: postgres://username:password@host:port/database
Common mistakes:
Wrong host (use db in Docker, not localhost)
Special characters in password need URL encoding
Port mismatch (default is 5432)
# Docker Compose docker compose exec server psql $PG_DATABASE_URL -c "SELECT 1;" # Direct connection psql postgres://postgres:postgres@localhost:5432/default -c "SELECT 1;"
Create database if missing
# Docker Compose docker compose exec db createdb -U postgres default # Local PostgreSQL createdb -U postgres default
Redis Connection Failed Symptoms:
Worker fails to start
Error: Redis connection failed
Solutions:
# Check Redis redis-cli ping # Should return: PONG # Docker Compose docker compose ps redis docker compose logs redis # Kubernetes kubectl get pods -n twenty -l app=twenty-redis kubectl logs -n twenty -l app=twenty-redis
# Docker Compose docker compose exec server redis-cli -u $REDIS_URL ping # Direct connection redis-cli -u redis://localhost:6379 ping
Migration Issues Migrations Failed to Run Symptoms:
Server starts but database schema is incorrect
Error: relation does not exist
Solutions:
# Docker Compose docker compose exec server yarn database:migrate:prod # Kubernetes kubectl exec -n twenty deployment/twenty-server -- yarn database:migrate:prod # Local development npx nx run twenty-server:database:migrate:prod
Reset database (development only)
This will delete all data!
# Docker Compose docker compose exec server yarn database:reset # Local development npx nx database:reset twenty-server
# Docker Compose docker compose exec db psql -U postgres default -c \ "SELECT * FROM typeorm_migrations ORDER BY timestamp DESC LIMIT 5;"
Migration Lock Issues Symptoms:
Migrations stuck or timeout
Error: could not obtain lock
Solutions: # Check for locks docker compose exec db psql -U postgres default -c \ "SELECT * FROM pg_locks WHERE NOT granted;" # Kill blocking queries (use with caution) docker compose exec db psql -U postgres default -c \ "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle in transaction';"
Symptoms:
Pages load slowly
API requests timeout
Solutions:
Check database performance
# Analyze tables docker compose exec db psql -U postgres default -c "ANALYZE;" # Vacuum database docker compose exec db psql -U postgres default -c "VACUUM ANALYZE;" # Check database size docker compose exec db psql -U postgres default -c \ "SELECT pg_size_pretty(pg_database_size('default'));"
# Redis stats docker compose exec redis redis-cli INFO stats # Cache hit rate docker compose exec redis redis-cli INFO stats | grep keyspace # Clear cache if needed docker compose exec redis redis-cli FLUSHDB
# Docker Compose - check container stats docker stats # Kubernetes - check pod resources kubectl top pods -n twenty kubectl describe pod < pod-nam e > -n twenty
Increase resources if needed:
Add resource limits in docker-compose.yml
Increase Kubernetes resource requests/limits
High Memory Usage Solutions: # Check memory usage docker stats --no-stream # Restart services to clear memory docker compose restart server worker # Kubernetes: restart pods kubectl rollout restart deployment/twenty-server -n twenty kubectl rollout restart deployment/twenty-worker -n twenty
Authentication Issues Unable to Sign In Symptoms:
Login fails with generic error
OAuth redirect fails
Solutions:
Ensure APP_SECRET is set and consistent across all services: # Docker Compose docker compose exec server env | grep APP_SECRET docker compose exec worker env | grep APP_SECRET
Verify OAuth configuration
For Google/Microsoft OAuth:
Callback URLs must match exactly
Client ID and secret must be correct
OAuth app must be published/verified
# Check OAuth settings docker compose exec server env | grep AUTH_GOOGLE
# Verify token expiration settings docker compose exec server env | grep TOKEN_EXPIRES
Ensure tokens aren’t expiring too quickly. Solutions:
Check Redis is running and accessible
Verify REDIS_URL is correct
Check system time is synchronized (NTP)
Verify browser cookies are enabled
File Upload Issues Files Not Uploading Symptoms:
File upload fails silently
500 error on upload
Solutions:
Check storage configuration
# Verify storage type docker compose exec server env | grep STORAGE_TYPE # For local storage, check permissions docker compose exec server ls -la /app/packages/twenty-server/.local-storage
Verify:
S3 credentials are correct
Bucket exists and is accessible
Bucket CORS policy allows uploads
IAM permissions include s3:PutObject
# Check S3 settings docker compose exec server env | grep STORAGE_S3
# Docker Compose docker compose exec server df -h docker volume inspect twenty_server-local-data # Kubernetes kubectl describe pvc twenty-storage -n twenty
Email Issues Emails Not Sending Symptoms:
Password reset emails not received
Invitation emails not sent
Solutions:
docker compose exec server env | grep EMAIL_DRIVER
For development, EMAIL_DRIVER=logger outputs to logs instead of sending.
# Test SMTP from container docker compose exec server curl -v telnet:// $EMAIL_SMTP_HOST : $EMAIL_SMTP_PORT
Email sending happens in background jobs: docker compose logs -f worker | grep email
Verify email configuration
Common issues:
Wrong SMTP port (use 587 for TLS, 465 for SSL)
Authentication required but credentials missing
App-specific password needed (Gmail)
Firewall blocking outbound SMTP
Worker Issues Background Jobs Not Processing Symptoms:
Webhooks not firing
Emails queued but not sent
Imports/exports stuck
Solutions:
# Docker Compose docker compose ps worker docker compose logs -f worker # Kubernetes kubectl get pods -n twenty -l app=twenty-worker kubectl logs -n twenty -l app=twenty-worker -f
Workers need Redis for job queues: docker compose exec worker redis-cli -u $REDIS_URL ping
# View queue stats docker compose exec redis redis-cli KEYS bull: * docker compose exec redis redis-cli LLEN bull:default:wait
# Docker Compose docker compose restart worker # Kubernetes kubectl rollout restart deployment/twenty-worker -n twenty
Debugging Techniques Enable Debug Logs Increase log verbosity:
# Update .env or ConfigMap LOG_LEVELS = error,warn,log,debug LOGGER_DRIVER = console
Restart services to apply:
docker compose restart server worker
Access Container Shell # Server docker compose exec server /bin/sh # Worker docker compose exec worker /bin/sh # Database docker compose exec db /bin/bash
Check Service Health # Health endpoint curl http://localhost:3000/healthz # GraphQL endpoint curl http://localhost:3000/graphql \ -H "Content-Type: application/json" \ -d '{"query": "{ __typename }"}' # REST API curl http://localhost:3000/rest/people \ -H "Authorization: Bearer YOUR_API_KEY"
Inspect Database Schema # List all tables docker compose exec db psql -U postgres default -c "\dt" # Check specific table docker compose exec db psql -U postgres default -c "\d+ metadata.objectMetadata" # View recent migrations docker compose exec db psql -U postgres default -c \ "SELECT * FROM typeorm_migrations ORDER BY timestamp DESC LIMIT 5;"
Common Error Messages ”APP_SECRET must be set” Cause: Missing or empty APP_SECRET environment variableSolution: # Generate secure secret openssl rand -base64 32 # Add to .env APP_SECRET = your-generated-secret-here # Restart docker compose restart server worker
“Port 3000 already in use” Cause: Another service is using port 3000Solution: # Find what's using the port lsof -i :3000 # or netstat -tulpn | grep :3000
“Relation does not exist” Cause: Database schema not initialized or migrations not runSolution: # Run migrations docker compose exec server yarn database:migrate:prod # Or reset database (development only) docker compose exec server yarn database:reset
“Invalid token” or “Unauthorized” Cause: Token validation failedSolutions:
Verify APP_SECRET matches across server and worker
Check token hasn’t expired
Regenerate API key if using API authentication
Clear browser cookies and sign in again
High CPU Usage Investigation: # Check which process is using CPU docker stats --no-stream # View slow queries docker compose exec db psql -U postgres default -c \ "SELECT query, calls, total_exec_time, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
Solutions:
Add database indexes for frequently queried fields
Optimize GraphQL queries
Enable Redis caching
Scale worker replicas
High Memory Usage Investigation: # Memory usage by container docker stats --no-stream # Node.js heap usage docker compose exec server node -e "console.log(process.memoryUsage())"
Solutions:
Increase container memory limits
Restart services periodically
Check for memory leaks in logs
Scale horizontally instead of vertically
Disk Space Issues Investigation: # Check disk usage docker compose exec server df -h # Database size docker compose exec db psql -U postgres default -c \ "SELECT pg_size_pretty(pg_database_size('default'));" # Docker volume size docker system df -v
Solutions:
Clean up old Docker images: docker image prune -a
Archive old data
Increase volume size
Configure log rotation
Webhook Issues Webhooks Not Firing Symptoms:
External systems not receiving events
Webhook jobs stuck in queue
Solutions:
Check webhook configuration
Query webhooks via GraphQL: query { webhooks { id targetUrl operation isActive } }
docker compose logs -f worker | grep webhook
Verify target URL is accessible: docker compose exec server curl -X POST https://your-webhook-url.com/webhook \ -H "Content-Type: application/json" \ -d '{"test": true}'
# View webhook jobs in Redis docker compose exec redis redis-cli KEYS bull:webhook * docker compose exec redis redis-cli LLEN bull:webhook:wait
Data Integrity Issues Symptoms:
Custom objects not appearing
Field changes not reflected
Solution: # Sync metadata manually docker compose exec server yarn command workspace:sync-metadata # Kubernetes kubectl exec -n twenty deployment/twenty-server -- yarn command workspace:sync-metadata
Data Inconsistencies Investigation: # Check for orphaned records docker compose exec db psql -U postgres default -c \ "SELECT COUNT(*) FROM core.person WHERE workspaceId NOT IN (SELECT id FROM core.workspace);" # Validate foreign key constraints docker compose exec db psql -U postgres default -c \ "SELECT conname, conrelid::regclass FROM pg_constraint WHERE contype = 'f';"
Docker-Specific Issues Cannot Pull Docker Image Solutions: # Check Docker Hub rate limits docker pull twentycrm/twenty:latest # Login if using private registry docker login # Try specific version docker pull twentycrm/twenty:v0.2.1
Volume Permission Issues Symptoms:
Cannot write files
Permission denied errors
Solution: # Check volume ownership docker compose exec server ls -la /app/packages/twenty-server/.local-storage # Fix permissions docker compose exec server chown -R node:node /app/packages/twenty-server/.local-storage
Kubernetes-Specific Issues Pods in CrashLoopBackOff Investigation: # Check pod status kubectl describe pod < pod-nam e > -n twenty # View logs kubectl logs < pod-nam e > -n twenty --previous
Common causes:
Database not ready (check init containers)
Missing secrets or ConfigMaps
Insufficient resources
Failed health checks
PVC Not Binding Investigation: # Check PVC status kubectl get pvc -n twenty kubectl describe pvc < pvc-nam e > -n twenty # Check storage class kubectl get storageclass
Solutions:
Ensure storage class exists and is default
Check PV availability
Verify access mode matches (ReadWriteMany for shared storage)
Getting Help Before asking for help, gather:
# Version information docker compose exec server cat package.json | grep version # System info uname -a docker --version # Logs docker compose logs > twenty-logs.txt # Configuration (remove secrets!) docker compose config
Discord Join our Discord community for real-time help
GitHub Issues Report bugs and request features
Documentation Browse the full documentation
Discussions Ask questions in GitHub Discussions
Next Steps
Configuration Review configuration options
Docker Compose Docker deployment guide
Kubernetes Kubernetes deployment guide
Monitoring Set up monitoring
