Debugging

Surfaces and runbooks for the most common "what's going on?" questions.

Logs

Cal.diy uses tslog (re-exported from packages/lib/logger.ts and packages/lib/logger.server.ts). Log levels are controlled by NEXT_PUBLIC_LOGGER_LEVEL (client) and LOG_LEVEL (server), defaulting to info. Server logs include request ID and (when available) booking UID and user ID.

For Trigger.dev background jobs, see packages/lib/triggerDevLogger.ts — these jobs ship logs to the Trigger.dev dashboard.

PII redaction lives in packages/lib/redactSensitiveData.ts and packages/lib/piiFreeData.ts. When in doubt, redact.

Sentry

Sentry is wired in three places:

• apps/web/sentry.server.config.ts
• apps/web/sentry.edge.config.ts
• apps/web/instrumentation-client.ts

The free instrumentation.ts re-exports the right module for the runtime. apps/api/v2/src/instrument.ts provides the same surface for the NestJS service. Errors thrown in services that descend from ErrorWithCode (packages/lib/errorCodes.ts) are tagged with their machine-readable error code, which makes Sentry searches much faster.

Common failure modes

Symptom	Likely cause	Fix
prisma generate errors about missing enums	Schema changed without regenerating	yarn workspace @calcom/prisma prisma generate
ENOENT on apps/api/v2/.env	Forgot to copy template	cp apps/api/v2/.env.example apps/api/v2/.env
Booking creation 500s with ErrorCode.NoAvailableUsersFound	Slot was double-booked or schedule changed under us	See packages/lib/errorCodes.ts for the full list
Calendar integration silently fails	OAuth token expired and refresh failed	Inspect the Credential row; the integration's lib/CalendarService.ts typically logs a redacted refresh attempt
401 from /api/trpc/...	NextAuth cookie missing or NEXTAUTH_SECRET drift	Re-login; verify .env matches what the running process saw
Tests fail with non-UTC timestamps	Forgot TZ=UTC	TZ=UTC yarn test
Embed iframe stuck on loading	embed.css blocked by strict CSP, or wrong NEXT_PUBLIC_EMBED_LIB_URL	Check the network tab for the snippet URL; see packages/embeds/embed-core/src/embed-iframe.ts
Type errors after pulling	Generated app-store files out of date	yarn app-store:build
Booking webhooks not firing	Tasker queue not draining; a Trigger.dev job is stuck	Inspect rows in the Task Prisma model and the Trigger.dev dashboard

Troubleshooter

The product has a built-in availability troubleshooter that visualizes how slots are computed for a given event type. The implementation is split across:

• apps/web/modules/troubleshooter/
• packages/features/troubleshooter/
• packages/lib/availability.ts

If a customer complains "I have no slots", reproduce with the troubleshooter UI — it shows exactly which schedules, busy times, and date overrides are being applied.

Prisma Studio

yarn db-studio

Opens Prisma Studio on http://localhost:5555. The fastest way to inspect a Booking, its BookingReferences, and the Credential rows of the organizer.

Strict mode + warnings

The Next.js config (apps/web/next.config.ts) keeps React strict mode on. Render warnings in dev are real bugs, not noise. The Pages Router and App Router coexist; some warnings are about routes still being migrated.

Checkly synthetics

__checks__/ contains synthetic checks that exercise critical paths against staging. If a deploy passes locally but Checkly fails, look at the check definition before re-rolling.