Skip to main content

Troubleshooting

Quick solutions for common CalendarPipe issues organized by category.

tip

Use the Test button in the Code Editor to debug gate functions against real events before saving. This is the fastest way to identify why events are not syncing as expected.

Sync Issues​

Sync Delays​

Symptom: Events appear in the source calendar but have not shown up in the synced calendar yet.

Why it happens: CalendarPipe syncs calendars on a scheduled cron worker. Free plan calendars sync every 15 minutes; Pro plan calendars sync every 5 minutes. There is no manual sync trigger available in the UI.

Resolution: Wait for the next sync cycle. If events are still missing after two cycles, check for gate function issues (see Gate Function Issues) or authentication issues (see Authentication Issues).

Events Not Syncing​

Symptom: Sync runs without errors but specific events do not appear on the target calendar.

Why it happens: Your gate function may be returning { pass: false } for those events, or the function may have a runtime error that is silently blocking them.

Resolution: Open the Code Editor on the sync rule and use the Test button to dry-run your gate function against real events from your source calendar. Verify that the gate function returns { pass: true } for the events you expect to pass. See Code Editor for details.

Authentication Issues​

Google or Microsoft OAuth Token Expired​

Symptom: Sync logs show an authentication error for a Google or Microsoft calendar. Events stop syncing.

Why it happens: OAuth access tokens expire and require a refresh token exchange. CalendarPipe cannot refresh the token automatically if the refresh token itself has expired or been revoked (this can happen if the user revokes app access or if the token has been unused for an extended period).

Resolution: Reconnect the calendar from the Connections page in the CalendarPipe dashboard. This will re-run the OAuth flow and obtain a new valid token pair.

Apple Calendar Password Rejected​

Symptom: CalDAV or connector setup for Apple Calendar fails with an "incorrect password" or "authentication failed" error.

Why it happens: Apple requires an app-specific password for third-party applications. Using your Apple ID password directly is not permitted.

Resolution: Generate an app-specific password at appleid.apple.com under Sign-In and Security > App-Specific Passwords. Use that password instead of your Apple ID password when connecting Apple Calendar. See the Apple Calendar connector guide for step-by-step instructions.

CalDAV Issues​

CalDAV Connection Fails​

Symptom: CalDAV client shows "Cannot connect to server" or "Server not found" when adding a CalendarPipe account.

Why it happens: The most common causes are a missing trailing slash in the server URL or using your account password instead of an API key.

Resolution:

  1. Verify the server URL is exactly: https://www.calendarpipe.com/api/caldav/ (the trailing slash is required)
  2. Use your CalendarPipe API key as the password — not your account login password
  3. Your username is your CalendarPipe account email address

See CalDAV Setup for per-client instructions including Apple Calendar and Thunderbird.

Hosted Calendar Not Visible in Apple Calendar​

Symptom: CalDAV account was added successfully to Apple Calendar, but the hosted calendar does not appear in the calendar list.

Why it happens: CalDAV auto-discovery can take a few minutes to propagate after adding the account. Occasionally the API key may lack the required permissions.

Resolution: Wait 2-3 minutes and refresh Apple Calendar. If the calendar still does not appear, verify that the API key you used is active and has not expired. Re-entering the account credentials in Apple Calendar system preferences can also trigger a fresh discovery request.

ICS Feed Issues​

ICS Feed Shows No Events​

Symptom: Subscribing to an ICS feed URL returns an empty calendar or shows no events.

Why it happens: Several causes are possible: the feedToken in the URL may be incorrect, the hosted calendar may have no events, or the feed cache may not yet include recently added events.

Resolution:

  1. Verify the feedToken by calling GET /api/v1/hosted-calendars and checking the feedToken field on the calendar
  2. Confirm the hosted calendar has events by calling GET /api/v1/hosted-calendars/{id}/events
  3. ICS feeds are cached with a 1-hour TTL -- events added in the last hour may not appear immediately. Wait for the cache to expire.

Billing Issues​

402 Payment Required or Quota Limit​

Symptom: API calls return 402 Payment Required or a dashboard message indicates you have hit a feature limit.

Why it happens: The requested feature or resource limit requires a Pro plan.

Resolution: Upgrade to Pro under Settings > Billing in the CalendarPipe dashboard. See Billing & Plans for plan comparison and upgrade options.

Webhook Issues​

Webhook Not Receiving Events​

Symptom: A hosted calendar has a webhook registered, but your endpoint is not receiving any POST requests.

Why it happens: Common causes include a non-HTTPS URL, incorrect secret format, or an endpoint that does not return a 2xx status code.

Resolution:

  1. Verify the webhook URL starts with https:// — plain HTTP is rejected
  2. Verify the webhook secret starts with whsec_
  3. Ensure your endpoint returns a 2xx HTTP status code — CalendarPipe marks delivery as failed and may retry if it receives 4xx or 5xx

See the Webhooks guide for registration steps and payload details.

HMAC Verification Fails​

Symptom: Your webhook handler computes a signature that never matches the webhook-signature header.

Why it happens: Two common mistakes: (1) using the full whsec_... string as the HMAC key without stripping the prefix, or (2) computing the HMAC over a parsed JSON object instead of the raw request body string.

Resolution:

  1. Strip the whsec_ prefix from your secret before passing it to createHmac
  2. Use the raw request body as a string (not JSON.stringify(req.body) which may alter whitespace or key ordering)

See the verification code example for a complete, copy-pasteable implementation.

Invitation Issues​

Invitation Not Delivered​

Symptom: An event was created with attendees but the attendees did not receive an invitation email.

Why it happens: For standard email recipients, CalendarPipe sends invitations via Resend -- the email may have been filtered as spam. For cal-*@in.calendarpipe.com addresses (other CalendarPipe hosted calendars), delivery is internal and does not go through email -- use polling or webhooks to receive those invitations.

Resolution:

  • For regular email recipients: ask the attendee to check their spam or junk folder
  • For cal-*@in.calendarpipe.com addresses: use GET /api/v1/hosted-calendars/{id}/invitations?status=pending to poll, or register a webhook to receive real-time delivery

See the Invitations guide for the full flow.

Loop Prevention Triggered​

Symptom: Invitations are created but immediately dropped or not delivered. Sync logs may reference loop prevention.

Why it happens: The organizer email on the event is a cal-*@in.calendarpipe.com address. CalendarPipe skips internal routing for events where the organizer is a cal-* address to prevent infinite invitation loops.

Resolution: Ensure the organizer email is a real external email address, not a CalendarPipe inbound address. Set the organizerDisplayName field when creating the hosted calendar to control the display name shown on invitations without affecting the underlying organizer address.

Gate Function Issues​

Gate Function Errors​

Symptom: Events stop syncing after editing a gate function, or sync logs show runtime errors.

Why it happens: The gate function may have a syntax error, a runtime exception, or may be returning an unexpected value type.

Resolution:

  1. Open the Code Editor on the affected sync rule
  2. Check for syntax errors highlighted in the editor
  3. Ensure the function is named gate and returns a GateResult object or a boolean -- any other return type is treated as a block
  4. Use the Test button to dry-run the function against real events and inspect the per-event results

See the Code Editor guide for full details on function signatures, return types, and the test runner.

Still Need Help?​

If these steps do not resolve your issue, contact CalendarPipe support. Include any relevant sync rule IDs, hosted calendar IDs, and the approximate time the issue occurred to help us investigate quickly.