Skip to content
Docs home

TROUBLESHOOTING · UPDATED AUGUST 2026

Common Issues

Symptom-first troubleshooting: slot not offered, booking failed, reminder not delivered, calendar drift, webhook silence, domain not verifying, and self-host health.

The troubleshooting model

Start with the observed state: time, tenant, role, the affected object, the expected result, the actual result, and the recent change. Then classify the issue as configuration, permission, provider, application, data, or infrastructure, and choose the smallest reversible action. Retry only when the operation is safe and idempotent; if a record may have duplicated, reconcile before retrying; if the system is rate-limited, respect the retry signal.

jsonhealthz — the first diagnostic call
$ curl -s https://your-deployment.example.com/api/public/healthz
{
  "status": "ok",
  "db": "ok",
  "db_ms": 4,
  "uptime_ms": 2147841029,
  "ts": 1787011200000
}

A healthy healthz answers with its own state — platform status, a live database check with latency, and uptime. If db is not ok, the problem is below the application; if the endpoint itself does not respond, the problem is at the edge or the process. From there the ladders below move outward from the symptom.

Slot not offered

  1. Goal
    A customer expects a slot that does not appear.
    Action
    Check the availability dimensions in order: service duration, staff schedule and overrides, required resources, existing bookings, location schedule, timezone.
    Result
    One dimension rejects the window — fix that configuration rather than working around it.

Booking creation fails

  1. Goal
    A booking cannot be created.
    Action
    Read the typed error. Check the five rejection classes: not offered, not available, not permitted, provider unavailable, configuration incomplete.
    Result
    The error names the boundary that rejected the request; recovery follows the class.

Reminder not delivered

  1. Goal
    A customer did not receive an expected reminder.
    Action
    Open the notification log: check the message status (pending/sent/failed/suppressed/cancelled), the channel's rate state, and the tenant's enabled channels. Remember that SMS-opted-out customers are skipped except for the booking_created wave.
    Result
    A failed status shows exhaustion of the retry budget; a suppressed status shows a policy skip. Fix the channel configuration or accept the policy outcome.

Calendar out of sync

  1. Goal
    A staff calendar does not reflect bookings.
    Action
    Check the staff member's Google connection status, run sync-now, and verify the booking's state (cancelled bookings remove their events). For external feeds, verify the feed URL still serves and resync.
    Result
    Google events reflect QUE state; feed events reflect the external source.

Payment status not updating

  1. Goal
    A paid booking still shows pending.
    Action
    Verify the inbound webhook secret is configured (unset → endpoint reports unavailable), check the delivery history for the Stripe webhook, and reconcile from the booking's stored provider session reference.
    Result
    Payment status reflects what the provider's signed event reported.

Outbound webhook not firing

  1. Goal
    Events are not reaching an endpoint.
    Action
    Walk the chain in order: (1) webhook enabled and subscribed to the event (or *); (2) delivery history for response codes; (3) if a secret is set, re-test with signature verification — a receiver that rejects an invalid signature is actually working correctly; (4) re-test the endpoint from the webhook record.
    Result
    Delivery history shows each attempt's response, including the 60-second retry cadence; a repeatedly failing endpoint stays visible rather than silently dying.

Domain not verifying

  1. Goal
    A custom booking domain stays unverified.
    Action
    Re-check the DNS records the verification asked for (exact host, exact value), then request re-verification through the domain record. Remember unverified domains never serve traffic by design.
    Result
    Verification passes and the domain serves the booking surface.

Self-hosted deployment unhealthy

  1. Goal
    A self-hosted fleet misbehaves.
    Action
    Hit /api/public/healthz (status, db check, db_ms, uptime) and /api/public/metrics (with the bearer token). Walk the stack: database connection, Redis reachability, application logs through Loki, alert counts through the Alertmanager sink counters.
    Result
    The failure lands in one layer — configuration, permission, provider, application, data, or infrastructure — and the smallest reversible fix applies.

Exit conditions

An incident is not resolved when the screen loads once. Confirm the record, the audit trail, the operator view, the customer-facing state, and the monitoring signal. Record what changed, and whether a follow-up task is owed.

STILL READING

Something here still feels worth checking together.

This documentation describes the product exactly as it is implemented. If a behavior you expected is not here — or is here and does not match your deployment — tell the team. Implementation questions start on the contact page.