Troubleshooting

​

Viewing Logs

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

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

• 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
• Need remote DB/Redis access from another machine: Postgres/Redis ports bind to localhost by default for security
  • Solution: set shell environment variables before start, for example: POSTGRES_BIND_HOST=0.0.0.0 REDIS_BIND_HOST=0.0.0.0 REDIS_HTTP_BIND_HOST=0.0.0.0 docker compose --profile all up -d
• 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 inbox-zero setup again

​

Database Connection Errors

• 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

• This happens when the database password in .env doesn’t match the password stored in the Postgres Docker volume (e.g., you deleted .env without removing the volume first, then re-ran setup).
• Fix: stop containers and remove volumes so Postgres is recreated with the current password:
  docker compose --profile all down -v
  inbox-zero start
  

• 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

• 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

• 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

• 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

• SSL/TLS certificate issue
• Use Let’s Encrypt with Caddy for automatic HTTPS
• Or set up Nginx with Certbot

​

Performance Issues

• Check VPS resources: htop or docker stats
• Increase VPS RAM if consistently above 80%
• Consider using external managed database services

• Normal for Next.js applications (expect 500MB-1GB)
• If exceeding 1.5GB, check for memory leaks in logs
• Restart containers: docker compose restart web

​

AI Rules and Email Processing Errors

• This means your AI provider API key is missing, invalid, or out of credits.
• Verify LLM_API_KEY is set in .env.
• Check that your API key has billing credits. A ChatGPT Plus or Claude Pro subscription does not include API access — you need a separate API key with credits from the provider’s developer platform.
• You can change your AI provider on the Settings page in the app.

• Same cause — the AI provider must be correctly configured with a valid, funded API key.
• Check logs (inbox-zero logs -f) for specific error messages from the AI provider.

• Verify your Pub/Sub topic and subscription are configured correctly — see the Pub/Sub setup guide.
• The push subscription endpoint must be publicly accessible. For local development, use ngrok.
• Check that GOOGLE_PUBSUB_TOPIC_NAME and GOOGLE_PUBSUB_VERIFICATION_TOKEN are set in your .env.
• Verify the Gmail service account (gmail-api-push@system.gserviceaccount.com) has the Pub/Sub Publisher role on your topic.

​

Rate Limiting

• This can happen if your email account is connected to another service making requests.
• For Gmail: Visit https://myaccount.google.com/security and check “Your connections to third-party apps & services”
• For Outlook: Visit https://account.microsoft.com/privacy/app-access to review connected apps

• 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

​

Uninstalling / Starting Over

​

Quick reset

inbox-zero stop
docker compose -f ~/.inbox-zero/docker-compose.yml --profile all down -v
rm ~/.inbox-zero/.env
inbox-zero setup

docker compose --profile all down -v
rm apps/web/.env
inbox-zero setup

​

Full removal

inbox-zero stop
docker compose -f ~/.inbox-zero/docker-compose.yml --profile all down -v

docker compose --profile all down -v

# Standalone mode
rm -rf ~/.inbox-zero

# If running from the cloned repo
rm apps/web/.env

​

Getting Help

1. Check GitHub Issues for similar problems
2. Join the Discord community
3. Include relevant logs and your setup details when asking for help