Skip to main content

​
Viewing Logs

If you installed via the CLI, use the built-in logs command: 
inbox-zero logs            # Show last 100 lines
inbox-zero logs -f         # Follow logs in real-time
inbox-zero logs -n 500     # Show last 500 lines
If you’re running Docker directly, use: 
docker logs inbox-zero-services-web-1
docker logs inbox-zero-services-db-1
docker logs inbox-zero-services-redis-1

​
Container Won’t Start

Check logs for errors using the commands above. Common issues:
  • Port conflicts: Another service is using port 3000, 5432, or 6379
    • Solution: Set custom ports via environment variables before starting: WEB_PORT=3001 POSTGRES_PORT=5433 REDIS_PORT=6381 inbox-zero start
  • Insufficient memory: Container is being killed by OOM
    • Solution: Increase VPS RAM or add swap space
  • Missing environment variables: Check .env file exists and has required values
    • Solution: Run npm run setup again

​
Database Connection Errors

Error: “Can’t reach database server”
  • Wait 30-60 seconds for Postgres to fully initialize
  • Check database container is running: docker ps | grep postgres
  • Verify DATABASE_URL in .env matches your setup
Error: “relation does not exist”
  • Migrations haven’t run yet
  • Wait for web container to complete startup (check logs)
  • Manually run: docker exec inbox-zero-services-web-1 npm run db:migrate

​
OAuth Configuration Issues

Error: “redirect_uri_mismatch”
  • Your OAuth redirect URI doesn’t match what’s configured in Google/Microsoft console
  • Ensure NEXT_PUBLIC_BASE_URL is set correctly when running docker compose up
  • Add https://yourdomain.com/api/auth/callback/google to authorized redirect URIs
Error: “invalid_client”
  • GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET is incorrect
  • Double-check credentials in Google Cloud Console
  • Ensure no extra spaces or quotes in .env file

​
Application Not Accessible

Can’t access via domain:
  • Verify DNS records point to your VPS IP: dig yourdomain.com
  • Check firewall allows traffic on port 3000: sudo ufw status
  • Set up reverse proxy (Nginx/Caddy) for HTTPS
Can access via IP but not domain:
  • SSL/TLS certificate issue
  • Use Let’s Encrypt with Caddy for automatic HTTPS
  • Or set up Nginx with Certbot

​
Performance Issues

Slow response times:
  • Check VPS resources: htop or docker stats
  • Increase VPS RAM if consistently above 80%
  • Consider using external managed database services
High memory usage:
  • Normal for Next.js applications (expect 500MB-1GB)
  • If exceeding 1.5GB, check for memory leaks in logs
  • Restart containers: docker compose restart web

​
Rate Limiting

Rate limited by email provider (Gmail/Outlook): Rate limited by AI provider:
  • Use a different AI model with higher rate limits.
  • Move to a higher tier with your AI provider.
  • Slow down the rate at which you are making requests.

​
AWS-Specific Issues

For troubleshooting AWS Copilot deployments (service won’t start, migration issues, EarlyValidation errors, domain problems), see the Copilot Deployment troubleshooting section.

​
Getting Help

If you’re still stuck:
  1. Check GitHub Issues for similar problems
  2. Join the Discord community
  3. Include relevant logs and your setup details when asking for help