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

# Troubleshooting

> Solutions for common issues when self-hosting Cal.com

This guide covers the most common issues encountered when self-hosting Cal.com, along with their solutions.

## Onboarding / setup issues

### Stripe payment features not working

**Symptom:** Stripe-related features (paid events, app store payment integration) are not available, or you see errors when attempting to use payment features.

**Cause:** The Stripe integration requires several environment variables to be configured. These variables are defined across two files: `.env` (root) and `.env.appStore`. If they are missing or empty, the Stripe app will be marked as "not installed" and payment-related features will be unavailable.

**Solution:** Add the following variables to your `.env` file (root):

```env theme={null}
STRIPE_PRIVATE_KEY=sk_test_...
STRIPE_CLIENT_ID=ca_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

And in your `.env.appStore` file (or `.env` if using a single file):

```env theme={null}
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_...
```

<Note>
  Replace these with your actual Stripe API keys from the [Stripe Dashboard](https://dashboard.stripe.com/apikeys). If you don't need payment features, you can safely leave these empty — the app will function without them, but Stripe-related features will be disabled.
</Note>

***

## URL and redirect issues

### Redirect to `localhost:3000` after deployment

**Symptom:** After deploying Cal.com to a server or domain, login redirects or internal links point back to `http://localhost:3000` instead of your actual domain.

**Cause:** The environment variables `NEXTAUTH_URL` and `NEXT_PUBLIC_WEBAPP_URL` are not set to your production domain. These variables tell Cal.com and NextAuth where the app is hosted.

**Solution:** Update your `.env` file to use your actual domain:

```env theme={null}
# Replace with your actual domain
NEXT_PUBLIC_WEBAPP_URL=https://cal.yourdomain.com
NEXTAUTH_URL=https://cal.yourdomain.com
```

<Warning>
  Do **not** include a trailing slash in your URLs.
</Warning>

**Important notes:**

* `NEXTAUTH_URL` is optional if `NEXT_PUBLIC_WEBAPP_URL` is set — NextAuth will infer the base URL from the incoming request's `Host` header when `NEXTAUTH_URL` is not explicitly configured.
* For Docker deployments, these must be set **before** building the image, as `NEXT_PUBLIC_WEBAPP_URL` is a build-time variable (it is inlined by Next.js during the build). Rebuild the image after changing it.
* For Vercel deployments, you do **not** need to set `NEXTAUTH_URL` — Vercel automatically infers it from the deployment URL via the `VERCEL_URL` environment variable.

***

## Docker-specific issues

### API v2 service not starting

**Symptom:** After running `docker compose up -d`, the `calcom-api` service fails to start or immediately exits. The web app works, but API v2 endpoints (`/api/v2/...`) return connection errors.

**Cause:** The API v2 service requires several environment variables that are not in the root `.env.example`. If any required variable is missing, the service will throw a `Missing environment variable` error and exit on startup.

**Solution:** Add the following variables to your root `.env` file (the `docker-compose.yml` passes these to the `calcom-api` service):

```env theme={null}
# Required for API v2 (service will not start without these)
REDIS_URL=redis://redis:6379
JWT_SECRET=your_random_jwt_secret_here
NEXTAUTH_SECRET=your_nextauth_secret_here
CALENDSO_ENCRYPTION_KEY=your_32_character_encryption_key
STRIPE_API_KEY=sk_test_your_stripe_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# Optional (have sensible defaults)
WEB_APP_URL=https://cal.yourdomain.com
REDIS_PORT=6379
LOG_LEVEL=warn
```

<Note>
  `STRIPE_API_KEY` is the API v2 equivalent of `STRIPE_PRIVATE_KEY` used by the web app. Both are Stripe secret keys but are consumed by different services. If you don't need Stripe functionality in the API, you can set a placeholder value (e.g., `sk_test_placeholder`), but the variable must be present.
</Note>

You can generate secure secrets with:

```bash theme={null}
openssl rand -base64 32
```

Then restart the stack:

```bash theme={null}
docker compose down && docker compose up -d
```

Check the API v2 service logs for further details if it still fails:

```bash theme={null}
docker compose logs calcom-api
```

<Tip>
  The API v2 service has its own `.env.example` at `apps/api/v2/.env.example` with a complete list of all supported variables. Refer to it for the full configuration reference.
</Tip>

***

### `CLIENT_FETCH_ERROR` in logs

**Symptom:** The following error appears in Docker logs, and login/session fails:

```
[next-auth][error][CLIENT_FETCH_ERROR]
request to http://<your-domain>/api/auth/session failed, reason: getaddrinfo ENOTFOUND
```

**Cause:** The Docker container cannot resolve the external hostname set in `NEXTAUTH_URL` from within the container's network.

**Solution:** Add your domain to the container's `/etc/hosts` so it resolves to itself:

```yaml theme={null}
# docker-compose.yml
services:
  calcom:
    extra_hosts:
      - "cal.yourdomain.com:127.0.0.1"
```

This allows the container to resolve your public domain internally while keeping `NEXTAUTH_URL` set to your public URL (required for OAuth callbacks to work).

<Warning>
  This approach works when `NEXTAUTH_URL` uses HTTP (e.g., `http://cal.yourdomain.com:3000`). If your `NEXTAUTH_URL` uses HTTPS, the container will attempt to connect to `127.0.0.1:443`, while the app listens on port 3000 — this will fail. In that case, ensure your reverse proxy is also running inside the Docker network, or see the SSL section below.
</Warning>

<Warning>
  Do **not** set `NEXTAUTH_URL` to `localhost` — this would fix the DNS error but **breaks OAuth**. External providers like Google would redirect to `localhost` instead of your domain.
</Warning>

***

### SSL / HTTPS issues behind a reverse proxy

**Symptom:** Requests fail with SSL certificate errors when Cal.com is behind a load balancer or reverse proxy that handles HTTPS termination.

**Solution:** Choose one of the following approaches:

<AccordionGroup>
  <Accordion title="Option 1: Use HTTP internally (recommended)">
    Keep `NEXTAUTH_URL` set to your **public-facing HTTPS URL**:

    ```env theme={null}
    NEXTAUTH_URL=https://cal.yourdomain.com
    ```

    Then configure your reverse proxy to forward the appropriate headers so internal requests work correctly:

    ```nginx theme={null}
    # Nginx example
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    ```
  </Accordion>

  <Accordion title="Option 2: Add internal CA to trusted certificates">
    If you are using self-signed certificates internally, add your internal CA to Node's trusted certificates:

    ```env theme={null}
    NODE_EXTRA_CA_CERTS=/path/to/your-internal-ca.crt
    ```
  </Accordion>

  <Accordion title="Option 3: Disable TLS verification (not recommended)">
    ```env theme={null}
    NODE_TLS_REJECT_UNAUTHORIZED=0
    ```

    <Warning>
      This disables **all** TLS certificate verification globally, including external API calls to Stripe, Google Calendar, and other services. This makes your instance vulnerable to man-in-the-middle attacks. Only use this in isolated development environments where you fully control all network traffic.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Database issues

### First user setup fails

**Symptom:** Attempting to create the first admin user via the `/setup` page results in an error.

**Cause:** This can occur if the database migrations have not been applied, or if the database is in an inconsistent state.

**Solution:**

<Steps>
  <Step title="Apply database migrations">
    ```bash theme={null}
    # For development
    yarn workspace @calcom/prisma db-migrate

    # For production / Docker
    yarn workspace @calcom/prisma db-deploy
    ```
  </Step>

  <Step title="Verify database connectivity">
    Confirm that your `DATABASE_URL` in `.env` is correct and the database is accessible.
  </Step>

  <Step title="Check application logs">
    If the issue persists after migrations, check the application logs for the specific Prisma error message — it will indicate which field or constraint is failing.
  </Step>
</Steps>

<Note>
  The setup endpoint (`/auth/setup`) creates the first user with the `ADMIN` role. It only works when the `User` table is completely empty. If a previous setup attempt partially succeeded, you may need to manually clear the users table before retrying.
</Note>

***

## Getting further help

If your issue is not listed here:

1. Search the [Cal.com GitHub Issues](https://github.com/calcom/cal.com/issues) — many common problems have documented solutions in issue threads.
2. Check the [Cal.com Community](https://community.cal.com) forum.
3. Review the [Docker configuration](/self-hosting/docker) and [Installation guide](/self-hosting/installation) for any steps you may have missed.