---
title: 'Troubleshooting'
description: 'Solutions for common issues when running Inbox Zero'
---

## Viewing Logs

If you installed via the CLI, use the built-in logs command:
```bash
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:
```bash
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`
- **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

**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: P1000 / "authentication failed"**
- 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:
  ```bash
  docker compose --profile all down -v
  inbox-zero start
  ```

**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`

## AI Rules and Email Processing Errors

**AI-powered rules fail but manually created rules work:**
- 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.

**Can't create rules using AI prompt:**
- 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.

**Emails not processing automatically (Pub/Sub):**
- Verify your Pub/Sub topic and subscription are configured correctly — see the [Pub/Sub setup guide](/hosting/google-pubsub).
- 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

**Rate limited by email provider (Gmail/Outlook):**
- 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

**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](/hosting/aws-copilot#troubleshooting).

## Uninstalling / Starting Over

### Quick reset

To re-run setup without removing Google Cloud resources:

**If you used the CLI (standalone mode):**
```bash
inbox-zero stop
docker compose -f ~/.inbox-zero/docker-compose.yml --profile all down -v
rm ~/.inbox-zero/.env
inbox-zero setup
```

**If you're running from the cloned repo:**
```bash
docker compose --profile all down -v
rm apps/web/.env
inbox-zero setup
```

### Full removal

<Accordion title="Remove everything including Google Cloud resources">

**1. Stop and remove containers and volumes:**

If you used the CLI (standalone mode):
```bash
inbox-zero stop
docker compose -f ~/.inbox-zero/docker-compose.yml --profile all down -v
```

If you're running from the cloned repo:
```bash
docker compose --profile all down -v
```

**2. Remove local configuration:**

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

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

**3. Clean up Google Cloud resources:**

1. **Pub/Sub:** Go to [Subscriptions](https://console.cloud.google.com/cloudpubsub/subscription/list) and delete your subscription, then go to [Topics](https://console.cloud.google.com/cloudpubsub/topic/list) and delete your topic.
2. **OAuth credentials:** Go to [API Credentials](https://console.cloud.google.com/apis/credentials) and delete the OAuth client.
3. **Consent screen** (optional): Go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) and reset or delete it.
4. **APIs** (optional): Go to [Enabled APIs](https://console.cloud.google.com/apis/dashboard) and disable Gmail, People, Calendar, and Drive APIs if no longer needed.

</Accordion>

## Getting Help

If you're still stuck:
1. Check [GitHub Issues](https://github.com/elie222/inbox-zero/issues) for similar problems
2. Join the [Discord community](https://www.getinboxzero.com/discord)
3. Include relevant logs and your setup details when asking for help