Troubleshooting API and Database Issues

Purpose and Scope

This page helps operators separate three failure classes that can look similar during self-hosting: the API v2 container failing to boot, Prisma refusing to apply or reconcile database migrations, and integrations appearing disconnected because the required provider credentials are absent or misconfigured. Cal.diy is intended for self-hosters, so these remedies assume that you can edit environment files, rebuild or restart services, and run Prisma commands against the database that backs your instance. The goal is to restore service health without masking schema drift or losing production data.

Sources: apps/docs/content/troubleshooting.mdx, apps/docs/content/database-migrations.mdx

The troubleshooting docs describe API v2 startup as a Docker-specific issue: after docker compose up -d, the calcom-api service can exit while the web app continues to work, causing /api/v2/... requests to fail with connection errors. That distinction matters because a reachable web UI does not prove that every service in the deployment is healthy. Treat API v2 as a separate service with its own required environment variables, logs, and restart lifecycle, then confirm database state only after the service can start far enough to connect.

Sources: apps/docs/content/troubleshooting.mdx

Database errors need a more conservative response. The database migration guide explains that Cal.diy relies on Prisma migrations so schema changes are reproducible, transparent, and safer than directly changing schema.prisma in a running production database. When a migration workflow fails, avoid ad hoc schema edits as the first fix. Instead, identify whether the database has unapplied migrations, a mismatched _prisma_migrations table, or a local development state that should be reset and re-indexed.

Sources: apps/docs/content/database-migrations.mdx

Relevant Source Files

• apps/docs/content/troubleshooting.mdx - Defines the self-hosting troubleshooting page, including API v2 service startup symptoms, required API environment variables, URL-related deployment issues, and Stripe-related configuration failures.
• apps/docs/content/database-migrations.mdx - Documents the supported Prisma migration commands, the reason migrations are required, the P3005 non-empty schema error, migration resolution, and local reset guidance.
• apps/docs/content/_meta.ts - Places Database Migrations, Upgrading, Docker, Apps, and Deployments in the main docs navigation so readers can move from a failure to the relevant operating guide.
• apps/docs/content/apps/_meta.ts - Lists the app integration troubleshooting surface by provider, including Google and Daily, which are common examples of external service connectivity setup.
• apps/docs/content/apps/daily.mdx - Documents the Daily API key and optional scale-plan environment variable used by Daily video integration setup.
• apps/docs/content/apps/google.mdx - Documents Google Calendar API enablement, OAuth scopes, callback URLs, GOOGLE_API_CREDENTIALS, and app-store reseeding after adding credentials.

Diagnose API v2 Startup Failures

When API v2 endpoints return connection errors but the web application loads, start with the calcom-api service rather than browser routing. The troubleshooting guide states that the API v2 service can fail immediately when required variables are missing, because the service throws a Missing environment variable error on startup. In Docker deployments, the root .env is the important file for these values because the Compose setup passes them to the API service. Restarting repeatedly without fixing the environment will usually reproduce the same failure.

Sources: apps/docs/content/troubleshooting.mdx

Use the environment checklist below as the first remediation step for the API v2 service. REDIS_URL points the service to Redis, JWT_SECRET and NEXTAUTH_SECRET support token and auth behavior, CALENDSO_ENCRYPTION_KEY protects encrypted application data, and the Stripe values are required by the documented API v2 startup configuration. WEB_APP_URL, REDIS_PORT, and LOG_LEVEL are documented as optional with sensible defaults, but setting WEB_APP_URL explicitly is still useful in deployments where service-to-service URLs differ from local defaults.

# Required for API v2
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
WEB_APP_URL=https://cal.yourdomain.com
REDIS_PORT=6379
LOG_LEVEL=warn

The Stripe names are easy to confuse across services. The general troubleshooting page describes web-app payment configuration with STRIPE_PRIVATE_KEY, STRIPE_CLIENT_ID, STRIPE_WEBHOOK_SECRET, and NEXT_PUBLIC_STRIPE_PUBLIC_KEY, while the API v2 startup checklist uses STRIPE_API_KEY and STRIPE_WEBHOOK_SECRET. If payment features are not your immediate concern, still account for the API service’s required variable names when debugging boot failures. A valid-looking web .env can still be incomplete for API v2 because the services consume different keys.

Sources: apps/docs/content/troubleshooting.mdx

Resolve Database Migration and Prisma State Errors

For database work, prefer the repository’s Prisma migration commands over manual schema changes. The migration guide instructs operators to update the database with yarn workspace @calcom/prisma db-migrate or yarn workspace @calcom/prisma db-deploy. It also warns that changing schema.prisma without creating migrations can damage or delete production data, because Prisma may not know how to transform existing data safely. If you are modifying the codebase, create a migration, give it a short descriptive name such as user_add_email_verified, inspect the generated SQL, and commit it with the code that depends on it.

Sources: apps/docs/content/database-migrations.mdx

yarn workspace @calcom/prisma db-migrate
yarn workspace @calcom/prisma db-deploy

The specific Prisma error P3005 means the database schema is not empty while Prisma’s migration history does not match what it sees in the actual database. The guide explains that Prisma tracks applied migrations in _prisma_migrations; if that local migration database and the real schema disagree, Prisma asks you to baseline the existing database. The documented fix is to mark each already-applied migration as applied, replacing migration_name with the migration directory name you have verified. Run this only for migrations that truly match the current schema state.

Sources: apps/docs/content/database-migrations.mdx

yarn prisma migrate resolve --applied migration_name

For local development databases that are out of sync and disposable, the docs include a reset path for Prisma migrate state. It deletes rows from _prisma_migrations, then re-indexes migrations from the local prisma/migrations directory with prisma migrate resolve --applied. This is a recovery technique for local migration bookkeeping, not a blanket production instruction. Before using it, decide whether the database contains data you need, whether migrations have already changed real tables, and whether a safer baseline-by-baseline resolve is more appropriate.

Sources: apps/docs/content/database-migrations.mdx

DELETE FROM "_prisma_migrations";

ls -1a prisma/migrations/ | grep 2021 | xargs -I{} prisma migrate resolve --applied {}

Related Service Connectivity Checks

Some apparent API or database failures are actually external-service configuration gaps. The Google Calendar setup requires enabling the Google Calendar API, configuring OAuth consent, selecting calendar scopes, adding authorized redirect URIs for <Cal.diy URL>/api/integrations/googlecalendar/callback and <Cal.diy URL>/api/auth/callback/google, and storing the downloaded OAuth JSON string in GOOGLE_API_CREDENTIALS for both .env and .env.appStore. After adding the credentials, the docs instruct readers to run pnpm db-seed so the app store includes the Google Calendar integration.

Sources: apps/docs/content/apps/google.mdx

Daily video connectivity has a smaller but similar shape: the app docs instruct you to copy the Daily API key into DAILY_API_KEY in .env, and optionally set DAILY_SCALE_PLAN=true for scale-plan features such as video recording. If booking pages work but a provider-specific feature fails, verify the provider’s environment variables before assuming that API v2 or Prisma is broken. The app metadata file confirms that Google, Daily, and the other integration guides sit under the Apps section, which is the right next stop for provider-specific setup.

Sources: apps/docs/content/apps/daily.mdx, apps/docs/content/apps/_meta.ts

Quick Reference

Next Steps

Work from the outside inward: confirm URLs and environment files, verify the API v2 service starts, then inspect database migration state, and only then troubleshoot provider-specific app connectivity. If you changed a public URL or a build-time variable, rebuild or redeploy before testing again. If the error is tied to a calendar, video, or payment provider, move from this page to the relevant Apps guide instead of changing database state. For broader operational context, read Docker updates, database migrations, and environment URL guidance next.

Sources: apps/docs/content/_meta.ts, apps/docs/content/apps/_meta.ts