Skip to main content
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): 
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): 
NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_...
Replace these with your actual Stripe API keys from the Stripe Dashboard. 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.

​
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: 
# Replace with your actual domain
NEXT_PUBLIC_WEBAPP_URL=https://cal.yourdomain.com
NEXTAUTH_URL=https://cal.yourdomain.com
Do not include a trailing slash in your URLs.
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): 
# 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
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.
You can generate secure secrets with: 
openssl rand -base64 32
Then restart the stack: 
docker compose down && docker compose up -d
Check the API v2 service logs for further details if it still fails: 
docker compose logs calcom-api
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.

​
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: 
# 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).
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.
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.

​
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:
If you are using self-signed certificates internally, add your internal CA to Node’s trusted certificates:
NODE_EXTRA_CA_CERTS=/path/to/your-internal-ca.crt

​
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:
1

Apply database migrations

# For development
yarn workspace @calcom/prisma db-migrate

# For production / Docker
yarn workspace @calcom/prisma db-deploy
2

Verify database connectivity

Confirm that your DATABASE_URL in .env is correct and the database is accessible.
3

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.
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.

​
Getting further help

If your issue is not listed here:
  1. Search the Cal.com GitHub Issues — many common problems have documented solutions in issue threads.
  2. Check the Cal.com Community forum.
  3. Review the Docker configuration and Installation guide for any steps you may have missed.