> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getinboxzero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common issues when running Inbox Zero

## Viewing Logs

If you installed via the CLI, use the built-in logs command:

```bash theme={null}
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 theme={null}
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 theme={null}
  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](https://myaccount.google.com/security) and check "Your connections to third-party apps & services"
* For Outlook: Visit [https://account.microsoft.com/privacy/app-access](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 theme={null}
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 theme={null}
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 theme={null}
  inbox-zero stop
  docker compose -f ~/.inbox-zero/docker-compose.yml --profile all down -v
  ```

  If you're running from the cloned repo:

  ```bash theme={null}
  docker compose --profile all down -v
  ```

  **2. Remove local configuration:**

  ```bash theme={null}
  # 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