On this page
  1. The Web UI cannot reach the service
  2. A monitor or agent cannot read status
  3. Reading the logs
  4. Database is large
  5. An event did not synchronize
  6. A rule removal stopped or left events behind
  7. Activity is temporarily unavailable
  8. A rule is degraded
  9. Problems only an administrator can fix
  10. The Google Calendar API is turned off
  11. The Google Cloud project’s daily quota is used up
  12. Google no longer accepts the OAuth client
  13. Google accounts stop working 7 days after connecting
  14. Microsoft no longer accepts the OAuth client
  15. Instant Sync cannot reach the installation
  16. Instant Sync needs an HTTPS public address
  17. Calendar providers cannot reach the installation
  18. Problems you fix yourself
  19. Google no longer accepts your Google account
  20. Your Google account may not change the calendar
  21. The calendar no longer exists
  22. Google is slowing Calendar Ghost down
  23. Google refused for a reason Calendar Ghost does not recognize
  24. Microsoft no longer accepts your Microsoft account
  25. Your Microsoft account may not change the calendar
  26. Microsoft is slowing Calendar Ghost down
  27. Microsoft refused for a reason Calendar Ghost does not recognize
  28. A calendar account was disconnected
  29. Consent ends on “Unable to connect”
  30. Calendar permission was not granted
  31. Connect is unavailable: your plan’s calendar accounts
  32. An account’s address changed
  33. Microsoft sign-in stops with an error
  34. A connected account fails Check access
  35. Destination edits return
  36. A destination event was recreated
  37. A projected series appears twice after “this and following”
  38. The first sync of a large calendar is slow
  39. A recurring event keeps being restored and removed
  40. Incremental cursor expired
  41. I cannot sign in
  42. Email notifications are unavailable or never arrive
  43. Start syncing is unavailable: your plan’s rule limit
  44. Issue token is unavailable: your plan’s token limit
  45. Someone has more than their plan allows
  46. A plan cannot be removed, or its name is refused
  47. Held by your plan
  48. A rule held by an activated release stays stopped after rollback
  49. Getting more help

Troubleshooting

The Web UI cannot reach the service

Check docker compose ps, then request http://localhost:8000/health. Review container logs without posting credentials or event payloads publicly.

A monitor or agent cannot read status

GET /api/v1/status and /mcp accept an Integration Token from Settings → Connections → Integrations (self-hosting guide). Check the answer with curl -i:

If status answers but its verdict surprises you:

Reading the logs

The service writes one line per record to the container’s standard error, timestamped in UTC:

2026-10-01T18:04:12Z INFO calendar_sync.application.sync.sync_run run started rule=7f3c… run=ab12… mode=incremental reason=changes

Follow the logs live, or read the last hour:

docker compose logs -f app
docker compose logs --since 1h app

The service’s own lines, those of the calendar_sync loggers, are also kept in its rotating log files beside the database, so Settings → Administration → Storage → Download gets them without SSH access to the host. Uvicorn’s request and error lines stay in the container logs only.

Lines name a rule and a run only by their internal identifiers. They never contain event titles, descriptions, calendar identifiers, account emails, URLs, or tokens, but review them before posting them publicly anyway. Uvicorn’s own request and startup lines appear alongside them in their own format.

Each Sync Run, scheduled or started with Sync now, writes:

Reconcile now and Rule Removal write one reconciliation started/removal started line and one finished, failed, or interrupted line each. A provider call slower than 10 seconds is a WARNING slow provider call provider=google op=events.instances status=200 took=12.4s.

To judge whether a long run is still working, compare consecutive run progress lines for the same run=. Rules and Rule Details show the same count while a sync runs, as “380 of 840 checked”. If handled, decided, and provider_calls grow, the run is progressing; a large calendar on its first-run, daily-pass, or reprojection can take many minutes. A growing rate_limited count means Google is slowing the run down and it will finish later. If no run progress line appears for several minutes and no run finished or run failed follows, the run is waiting on a single Google call; look for slow provider call warnings, or turn on debug logging.

unrecognized provider reason provider=google status=403 reason=someNewReason (WARNING): Google refused a request for a reason Calendar Ghost does not recognize, so its Cause is unknown. The line names only Google’s short reason code, never its message, and says reason=unreadable when the code is not a short token. When Installation health says that two or more people fail for a reason Calendar Ghost does not recognize, look for these lines, and include the reason code when you report it so a later release can recognize it.

Set CALENDAR_SYNC_LOG_LEVEL=DEBUG in .env and run docker compose up -d to also log every provider call as provider call provider=google op=events.get status=200 took=84ms. Debug logging is verbose; set it back to INFO when you are done.

Database is large

Settings → Administration → Storage shows the database’s size, the number of Activity entries, and the oldest one. Clear Activity older than 30, 90, 180, or 365 days; the confirmation shows how many entries that removes before you confirm. Clearing deletes in batches and then compacts the database, which briefly waits for any rule that is synchronizing; if every rule’s lock cannot be taken, or SQLite stays locked, within 30 seconds, the response is “Old Activity was cleared, but its space could not be reclaimed while a rule is synchronizing. Try again when it finishes.” The entries are already gone at that point, so clearing again later reclaims the space without deleting anything further. See ADR 0019 for which entries are kept and why.

An event did not synchronize

Open Activity, filter by the rule, and choose Skipped or Blocked. Each row names the event and why no Event Projection was written; select it to see the full explanation, the event as the run recorded it, the event as it is in Google now, and a link to open it in Google Calendar. Common reasons:

A rule removal stopped or left events behind

A removal that is still running shows Removing with its progress, even after the page is reloaded, and keeps running if you leave. Restarting the service stops it partway.

Removal incomplete means the rule stopped partway and does not synchronize. Temporary Google errors are already retried with backoff before removal stops; choose Retry removal to continue from the remaining projections.

Activity is temporarily unavailable

The Activity screen names the reason it could not load audit entries and incidents:

A rule is degraded

A rule held by your plan is degraded without a new Incident. It resumes automatically when its Plan has room; Preview does not release its hold.

For other degraded rules, open Activity. The rule’s incident says what stopped it and offers the next step. The rule keeps its mappings and last successful incremental positions, and writes nothing while degraded.

To recover a rule stopped by one of these failures, open it, choose Preview to restart, inspect the preview, and choose Start syncing. Its next run repairs drift before advancing either cursor. The next successful scheduled run, within five minutes, resolves the incident; Sync Now and Reconcile Now do not.

Problems only an administrator can fix

Some failures come from the installation’s Google Cloud project or Microsoft Entra application, not from anyone’s account or calendars, so only an Installation Administrator can fix them. Outlook is verified with personal Microsoft accounts, such as Outlook.com and Hotmail. Microsoft 365 work or school accounts can connect, but are not yet verified: the checks in ADR 0034 have not yet run against one. Calendar Ghost reads why the provider refused from its reason code, never its message, and records it as a Cause. Each person’s own Overview says only that the calendar service is temporarily unavailable, without the cause or a mention of you, so people are not prompted to contact you. On People, Installation health says Needs you, People is marked in the navigation, and the likely cause is shown as soon as anyone meets it, with How to fix linking to the section below; a person’s page shows the likely cause of each of their problems. Administrators never need to contact anyone: once the project is fixed, each person’s dashboard tells them what, if anything, is left for them.

The Google Calendar API is turned off

Symptom. Rules stop with “Access to Google Calendar was denied” for several people at once, and the likely cause reads “the Google Calendar API is turned off for this installation”. Check access fails the same way for every account.

Confirm. In the Google Cloud Console, select the project that owns the OAuth client in CALENDAR_SYNC_GOOGLE_CLIENT_ID, open APIs & Services → Enabled APIs & services, and look for Google Calendar API. If it is missing, or its page offers Enable, it is off. A project that was suspended or marked for deletion answers the same way.

Fix. Choose Enable on the Google Calendar API page, and wait a few minutes for Google to apply it. Google refused each affected account while the API was off, so their rules stay stopped until each account is checked again. Calendar Ghost does that on its own within an hour, and a check that passes restarts every rule it stopped, with no preview. Meanwhile each person’s Overview says Google Calendar is temporarily unavailable and offers Check access on their Google account in Settings → Connections to try at once.

The Google Cloud project’s daily quota is used up

Symptom. Several people’s rules wait on Google, and the likely cause reads “this installation’s daily quota of Google requests is used up”. Nobody’s rules stop; they retry by themselves.

Confirm. In the Google Cloud Console, open APIs & Services → Google Calendar API → Quotas & System Limits for the project that owns the OAuth client, and compare the requests per day with the limit.

Fix. Google resets the daily quota at midnight Pacific Time, and rules catch up on their own after it. If it runs out again, request a higher limit on the same page, or reduce how much Calendar Ghost asks for: fewer rules, or rules over smaller calendars.

Google no longer accepts the OAuth client

Symptom. Every person’s Google accounts stop at the same time, the likely cause reads “Google no longer accepts this installation’s OAuth client”, and reauthorizing fails too.

Confirm. In the Google Cloud Console, open Google Auth Platform → Clients (older consoles: APIs & Services → Credentials) and find the OAuth 2.0 client whose ID is CALENDAR_SYNC_GOOGLE_CLIENT_ID. It may have been deleted, or its secret reset, so that CALENDAR_SYNC_GOOGLE_CLIENT_SECRET no longer matches. Do not post either value publicly.

Fix. Put the client’s current ID and secret in .env and run docker compose up -d. The first scheduled pass after the restart checks every stopped Google account again, and each check that passes restarts its rules. Each person’s Overview, which says Google Calendar is temporarily unavailable, also offers Check access on their Google account. If you had to create a new client, Google’s grants to the old one do not carry over: each person’s dashboard asks them to choose Reauthorize account once.

Google accounts stop working 7 days after connecting

Symptom. People’s Google accounts need reauthorization about a week after they connected or last reauthorized them, again and again. Installation health says so when it happens to two or more people.

Confirm. Google gives a refresh token that expires after 7 days to an OAuth app whose user type is External and whose publishing status is Testing. In the Google Cloud Console, open Google Auth Platform → Audience (older consoles: APIs & Services → OAuth consent screen) and read Publishing status.

Fix. Choose Publish app to move it to In production. Google may show people an “unverified app” warning until the app is verified; a household installation can continue past it. Grants given while the app was in Testing still expire, so each affected person reauthorizes once from their own dashboard; after that their access lasts. A Google Workspace organization can instead set the user type to Internal, which has no 7-day limit.

Microsoft no longer accepts the OAuth client

Symptom. Every person’s Microsoft accounts stop at the same time, the likely cause reads “Microsoft no longer accepts this installation’s OAuth client”, and reauthorizing fails too.

Confirm. In the Microsoft Entra admin center, or the Azure portal for a directory a personal account owns, open App registrations, find the application whose Application (client) ID is CALENDAR_SYNC_MICROSOFT_CLIENT_ID, and open Certificates & secrets. The secret in CALENDAR_SYNC_MICROSOFT_CLIENT_SECRET has most likely expired: each secret has an expiry date, at most 24 months after it was created. The application may also have been deleted. The service logs name Microsoft’s code, such as AADSTS7000222 for an expired secret (Reading the logs). Do not post either value publicly.

Fix. Choose New client secret, copy its Value (shown only once), put it in .env as CALENDAR_SYNC_MICROSOFT_CLIENT_SECRET, put its Expires date in CALENDAR_SYNC_MICROSOFT_CLIENT_SECRET_EXPIRES, and run docker compose up -d. The first scheduled pass after the restart checks every stopped Microsoft account again, and each check that passes restarts its rules; each person’s Overview also offers Check access on their Microsoft account. If you had to register a new application, Microsoft’s grants to the old one do not carry over: each person reauthorizes once. With the expiry date in .env, People warns you 30 days before the next secret expires, so you can create its successor in time.

Instant Sync cannot reach the installation

Instant Sync runs a rule soon after Google or Microsoft reports a change, and needs them to reach this installation from the internet. While it cannot, rules sync on their schedule, every five minutes, and nothing is lost. Installation health on People names the cause below as soon as anyone wants Instant Sync, with How to fix linking here.

Instant Sync needs an HTTPS public address

Symptom. Installation health says people want instant sync, but this installation’s public address uses plain HTTP. Each person’s Instant sync under Settings → Your account says Calendar Ghost needs a public HTTPS address.

Confirm. CALENDAR_SYNC_PUBLIC_URL in .env starts with http:// and names a host on the internet. A plain HTTP address on this machine or your home network is never hinted: providers cannot reach it, and people’s settings already say so.

Fix. Google and Microsoft report changes only to an https address with a valid certificate. Serve /api/v1/watch-notices/ through HTTPS, for example with a reverse proxy or Cloudflare Tunnel, set CALENDAR_SYNC_PUBLIC_URL to that https address, and run docker compose up -d. Within five minutes, Calendar Ghost asks each provider to report changes there. If you do not want Instant Sync, the hint does no harm: without an HTTPS address, Calendar Ghost asks no provider to report changes, and rules sync on their schedule. See Instant Sync for the requirements and proxy examples.

Calendar providers cannot reach the installation

Symptom. Installation health says people want instant sync, but Google or Microsoft cannot reach this installation. When no provider a person uses reaches it, their Instant sync says so beside its choice, and their rules say “Syncs every 5 minutes”. Calendar Ghost keeps asking the providers meanwhile; choosing On schedule there stops it.

Confirm. From a machine outside your network, send a request shaped like Google’s to an unknown registration. It changes nothing:

curl -i -X POST https://calendar.example.com/api/v1/watch-notices/google/00000000000000000000000000000000 \
  -H 'X-Goog-Channel-ID: 00000000000000000000000000000000' \
  -H 'X-Goog-Channel-Token: reachability-check' \
  -H 'X-Goog-Resource-ID: reachability-check' \
  -H 'X-Goog-Resource-State: exists'

Calendar Ghost answers 202 Accepted. A timeout, a 502 or 504, a 403 from a firewall, or a sign-in page means the proxy or tunnel stops the request before it reaches Calendar Ghost.

Fix. Make the proxy or tunnel forward POST /api/v1/watch-notices/ with its query string, headers, and body unchanged, and let it through any sign-in gate, such as Cloudflare Access, and any bot challenge. The certificate must be valid for the public name: providers refuse a self-signed one. Google’s notices count again with the next change in a watched calendar; Microsoft is asked again on Calendar Ghost’s next try, which waits longer after each failure, at most a day. See Forward the notices path for working proxy and tunnel examples.

Problems you fix yourself

When Google or Microsoft refuses one of your requests for a reason that is yours to handle, your Overview and the rule say what happened and your one next step. Your administrator sees only that you can fix it from your dashboard, and does not contact you about it. If the installation sends email and has a public address, the incident email links straight to that step.

Google no longer accepts your Google account

What you see. “A Google account needs reauthorization”, with the likely cause “Google no longer accepts this Google account’s permission”. You removed Calendar Ghost’s access in your Google account, changed something Google treats as ending the grant, or the grant expired.

What to do. Choose Reauthorize account in Settings → Connections, for the account it names. Every rule the lapse alone stopped restarts on its own, with no preview. If it happens again about a week after each reauthorization, tell your administrator: the installation’s Google app is probably in Testing mode (Google accounts stop working 7 days after connecting).

Your Google account may not change the calendar

What you see. The rule stopped, with the likely cause “the Google account may not change this calendar”. The calendar’s owner took away your account’s permission to make changes, or a Google Workspace policy limits it.

What to do. Open the rule. Choose another calendar for it, or remove it. To keep the same calendar, ask its owner to share it with your Google account with Make changes to events, then preview the rule again to restart it.

The calendar no longer exists

What you see. The rule stopped, with the likely cause “the calendar no longer exists, or is no longer shared with the account”. The calendar was deleted, or unshared from the account the rule uses.

What to do. Open the rule and choose another calendar for it, or remove the rule.

Google is slowing Calendar Ghost down

What you see. “Waiting for Google”, with the likely cause “Google asked Calendar Ghost to slow down” or “Google failed for a moment”, when the rule was last tried, and when it tries again.

What to do. Nothing. Calendar Ghost tries again by itself and catches up afterwards. If it lasts more than a day, check the Google Workspace Status Dashboard.

Google refused for a reason Calendar Ghost does not recognize

What you see. The rule stopped or needs a look, with the likely cause “Google refused for a reason Calendar Ghost does not recognize”.

What to do. Try the rule’s usual step again: open the rule and preview it to restart it, or read what Activity says. If it keeps happening, tell your administrator; the service logs name Google’s reason (Reading the logs).

Microsoft no longer accepts your Microsoft account

What you see. “A Microsoft account needs reauthorization”, with the likely cause “Microsoft no longer accepts this Microsoft account’s permission”. You removed Calendar Ghost’s access, your password was reset, your sign-in now needs another step such as multifactor authentication, or the grant went unused for 90 days.

What to do. Choose Reauthorize account in Settings → Connections, for the account it names. Every rule the lapse alone stopped restarts on its own, with no preview. With a work or school account, your organization may require its administrator to approve applications: if Microsoft says the application needs approval, ask your organization’s IT administrator to grant consent to it, then reauthorize.

Your Microsoft account may not change the calendar

What you see. The rule stopped, with the likely cause “the Microsoft account may not change this calendar”. The calendar was shared with your account to read only, or its owner took away your permission to edit it.

What to do. Open the rule. Choose another calendar for it, or remove it. To keep the same calendar, ask its owner to share it with your Microsoft account with Can edit, then preview the rule again to restart it.

Microsoft is slowing Calendar Ghost down

What you see. “Waiting for Microsoft”, with the likely cause “Microsoft asked Calendar Ghost to slow down” or “Microsoft failed for a moment”, when the rule was last tried, and when it tries again.

What to do. Nothing. Calendar Ghost tries again by itself, waiting as long as Microsoft asks, and catches up afterwards. If it lasts more than a day, check the Microsoft 365 service health status page.

Microsoft refused for a reason Calendar Ghost does not recognize

What you see. The rule stopped or needs a look, with the likely cause “Microsoft refused for a reason Calendar Ghost does not recognize”.

What to do. Try the rule’s usual step again: open the rule and preview it to restart it, or read what Activity says. If it keeps happening, tell your administrator; the service logs name Microsoft’s code (Reading the logs).

A calendar account was disconnected

Open Settings → Connections → Connected accounts and choose Reauthorize account for the same Google or Microsoft identity. The installation no longer retains credentials for a disconnected account, and enabled rules that reference it remain degraded. After reauthorization, open Rules, choose Validate recovery, inspect the preview, and enable each affected rule. Existing mappings, Managed Projections, and incremental positions are preserved throughout recovery.

To remove the local identity permanently, choose Delete account and review the destructive confirmation. Permanent deletion removes every affected Directional Sync Rule and its mappings, cursors, incidents, and audit activity. Existing Managed Projections are not deleted from Google Calendar or Outlook and will no longer be managed. Unrelated accounts and rules are unchanged.

After Google or Microsoft consent, the browser followed the configured redirect URI to an address that does not reach this installation, usually localhost while Calendar Ghost runs on another host. No account was saved. When the redirect URI is at another address than the one Calendar Ghost is open at, consent opens in a new tab, so the tab you started from stays on Calendar Ghost. To finish this attempt, copy the whole address from the new tab’s address bar, return to the Calendar Ghost tab, paste it into Address Google returned to (or Address Microsoft returned to) under Finish connecting your Google account (or Microsoft account), and choose Finish connecting within 10 minutes; each callback works once. From another browser, sign in there as the same person first; the same field is in the note at the foot of Connected accounts. Replacing the origin in the address bar by hand, for example localhost:18000 with 192.168.1.50:18000, does the same. Only the person who started connecting can finish: a callback opened without signing in, or by anyone else, connects nothing and reports that authorization failed. To stop it recurring, use an HTTPS redirect URI or an SSH tunnel as described in Deployment.

Calendar permission was not granted

The OAuth callback returns to Settings → Connections → Connected accounts without saving an account. Choose Try again, select the intended Google or Microsoft identity, and grant calendar access: for Google, both calendar-list and event access; for Microsoft, Have full access to your calendars. Calendar Ghost verifies those permissions before it stores the Connected Account. Declining consent does not create an account or retain any credentials.

Connect is unavailable: your plan’s calendar accounts

When an administrator has turned Plans on, your Plan may limit how many calendar accounts you have. Every account under Settings → Connections → Connected accounts counts, Disconnected Accounts too: connecting one of them again is Reauthorization, which a Plan never refuses. At the limit, Connect an account is unavailable and says why, but Reauthorization is never refused by the account limit: an account that needs it still offers Reauthorize account. Settings → Your account → Your plan shows how many calendar accounts you have and how many your Plan allows, as “2 of 1” beside a meter, and past the limit a sentence that links to Connections. Installation Administrators are never limited.

Calendar Ghost learns an account’s address only after the provider’s consent. So when you choose an address you have not connected, and your Plan has no room for it, you return to Connections with “Your plan’s calendar accounts are all in use”. No account was saved, and your existing accounts and rules are unchanged. The provider may keep the consent you gave; you can remove Calendar Ghost from your Google or Microsoft account’s security settings.

To make room, delete an account you no longer use (A calendar account was disconnected explains what deleting removes), or ask your administrator for a larger Plan.

If connecting a new account ends on an error page instead of Connections while Plans are on, Calendar Ghost could not read your Plan, for example because its database was busy. No account was saved; connect again. Reauthorizing an account you already have never reads your Plan.

An account’s address changed

Calendar Ghost knows each account by its provider and email address. When the address of a Microsoft or Google Workspace account changes, for example after a rename, the provider reports the new address, so reauthorizing connects a new account and the old one stays. At the limit, the new address is refused. To move every rule to the new address without losing one:

  1. Free one account place: delete an account you no longer use, or ask your administrator to raise your Plan’s account limit, or give you a larger Plan, for the move.
  2. Connect the new address.
  3. On each rule that uses the old account, choose Replace calendars… and choose the same calendar under the new address. Where the old account holds the rule’s destination, keep its events as ordinary events: the old account may no longer be able to delete them.
  4. Disconnect the old account, then delete it.

Delete the old account only after every rule has moved: deleting an account deletes the rules that use it.

Microsoft sign-in stops with an error

Microsoft shows its own page, with a code beginning AADSTS, instead of returning to Calendar Ghost. No account was saved.

A connected account fails Check access

If its provider no longer accepts the account, the check says so and the account is marked Needs reauthorization; choose Reauthorize account. If Google denied calendar access, the Google Calendar API may be off: it is enabled on the Google Cloud project, not separately on each Google identity. Confirm that the API remains enabled for the project owning the OAuth client, then choose Reauthorize account for the affected identity. If Microsoft denied calendar access, the grant most likely lacks calendar permission: choose Reauthorize account and accept calendar access. Check access verifies both calendar-list and event access through read-only requests. A successful check also reports the number of writable calendars; an account with zero writable calendars can be a Source Calendar but cannot provide a Destination Calendar.

Destination edits return

This is expected. Destination events are Managed Projections and source content is authoritative. Pause the rule before changing a destination projection that should temporarily remain untouched.

A destination event was recreated

Deleting a Managed Projection is Drift while its source remains eligible. Synchronization recreates it on the next destination change poll. Delete or exclude the source, or pause the rule instead.

A projected series appears twice after “this and following”

Editing or deleting a projected series in the destination with This and all following events splits it in two: the calendar service ends the series Calendar Ghost wrote, and makes a new series for the rest. Calendar Ghost puts its own series back as the source has it, but it did not write the new one, so it never changes or deletes it, as it would not change one of your own events. Delete the new series yourself. To change a projected series, change it in the source instead.

The first sync of a large calendar is slow

The first sync writes every event of the window one at a time, about one event a second into Google or Outlook; a calendar of a few hundred events takes several minutes, and Activity shows its progress. The runs after it write only what changed.

A recurring event keeps being restored and removed

Earlier releases showed a recurring event in Activity as added to the destination and then removed on every run when every occurrence of its Event Series was cancelled in the source, often after a “this and following” split. Google cancels a series once its last occurrence is cancelled, so the next run found no Event Projection and created it again. Upgrade to a release that includes migration 10 (see Deployment): the next run stops recreating the series, may record Skipped: no occurrence left to sync for it, and keeps the Series Mapping dormant until an occurrence is restored. An entry such as Removed from Work: no occurrence left to sync means the run removed a projection that an interrupted run had created; no action is needed.

The same happened, with Missing from Work, so put back again followed by Declined, so removed from Work, when every remaining occurrence of the series was declined, awaiting an answer, or answered Maybe under a rule that skips those. Upgrade to a release with that fix; the next run stops recreating the series and keeps it dormant until you accept one of its occurrences.

Incremental cursor expired

The Google adapter must discard the expired cursor, perform a safe initial-window scan, match managed projections through origin metadata, and establish a new cursor without duplicating events.

I cannot sign in

Email notifications are unavailable or never arrive

Email notifications under Settings → Your account appears only when the installation sends email. Until then that page says who can set email up. Activity keeps every incident; Your plan and held-rule views retain Plan state. These are also the fallback when a notice is lost during failed pass preparation, cancellation, shutdown, restart, or SMTP failure. A newer pending Plan notice can replace an older one for the same User; there is no outbox or retry. Identity and security mail is independent of this preference.

Start syncing is unavailable: your plan’s rule limit

Start syncing is unavailable on a rule’s preview page, or starting it answers that your plan’s limit is reached, when an administrator turned Plans on and the rules that count toward your Plan already reach its rule limit. Under Settings → Your account → Your plan, Active rules shows how many rules count and how many your Plan allows, as “1 of 1” with Limit reached, and beside Create sync rule on Rules a note says how many your Plan lets sync at once.

An API client receives 409 with the code plan_limit_reached and the reason rules, or rules_with_held when the User also has rules on Plan Hold. Both carry limit and count for the same limit. Rule details expose can_start, rule_limit, and held_rules for the matching preflight explanation; Start checks the Allowance again and refuses if it cannot be read. Held rules can take a free place at the next scheduled check; saving keep choices applies swaps immediately. See Held by your plan.

Issue token is unavailable: your plan’s token limit

Under Settings → Connections → Integrations, Issue token is unavailable when your unrevoked Integration Tokens reach your Plan’s token limit, and the form says why: “Your plan allows 2 integration tokens, and all are in use. Revoke one to issue another.” Revoke a token you no longer use, then issue the new one: revoked tokens do not count. A Plan may include no Integration Tokens at all; the form then says “Your plan does not include integration tokens. To get one, ask your administrator.” Integration tokens under Settings → Your account → Your plan shows how many you have against the limit, or Not included. Tokens you already have keep working when a limit is lowered, so no monitor stops on its own. A token that reads Installation Health is for administrators, who are never limited. An API client receives 409 with the code plan_limit_reached and the reason integration_tokens.

Someone has more than their plan allows

This is for administrators. After you lower a limit, or give someone a smaller Plan, some people can have more than their Plan allows. Rules counting beyond the limit get a seven-day grace. At expiry, excess running or lapse-stopped rules are held until there is room; excess replacement drafts give up their reserved places instead. Existing calendar accounts and Integration Tokens keep working. New Starts, connections, and token issues still require room within their corresponding limit. Before you save a lower limit, the Plan form says how many people it would leave with more: “1 person on Free has more calendar accounts than this. They keep them, but can’t connect another.”

People shows who they are, in Attention Ochre with an icon:

The person sees the same under Settings → Your account → Your plan, in their own words, with Over a limit beside their Plan’s name: “You have 2 calendar accounts and your plan allows 1. They keep syncing, but you can’t connect another until you remove one in Connections.”

Each count is made as the limit counts it: rules that count toward the Plan (Start syncing is unavailable says which), every calendar account, Disconnected Accounts too, and Integration Tokens not revoked. Administrators and disabled people are never limited, so they are never shown over a limit. While Plans are off, the same marks show what turning them on would do.

To fix it, do one of these:

A plan cannot be removed, or its name is refused

An API client receives 409 with the code plan_in_use, plan_is_default, or plan_name_taken.

Held by your plan

A neutral Held by your plan label means the rule is beyond its Plan’s rule limit after a seven-day grace, or your saved choice gave its place to another rule. Existing projections, mappings, and incremental positions remain. It is not a failure and creates no Incident or Audit Entry. Sync now and Reconcile now are unavailable while held; Preview is allowed and preserves the hold.

Open Choose which rules sync on the rule or under Settings → Your account → Your plan. Save the complete set of preferred rules, up to your current limit. Choose none to prefer the oldest rules. A save can swap a kept held rule with an active rule immediately, without email. The scheduled pass never swaps: if a competing Start filled a place before automatic release, save the choice again. When a place is free, the next scheduled check releases the best-ranked held rule without a new preview. Release checks both accounts; if either needs Reauthorization, the released rule waits for it instead. Reauthorization alone never releases a hold.

Pausing a held rule clears its hold, gives up no place, and needs a preview before a normal Start. A policy change, disconnection, or intervention failure also ends the hold and can leave recovery Start without room. The UI warns before capacity-losing actions. Plans off or administrator status releases holds on the next successful settlement. Disabled Users retain holds and clear grace. No scheduler means no automatic release: check Installation Status for stalled and restore the scheduler. Monitors read stop_cause or needs_attention; a held rule can be degraded without a Stopped problem. Status incident/block totals and Activity retain held-owned records even though Dashboard attention counts omit them.

A rule held by an activated release stays stopped after rollback

The older inert PR 2 and PR 3a builds recognize Plan Hold but their production scheduler does not release it. Restoring account access never releases a hold on those builds. Upgrade to an active release, or pause the rule to clear its hold, then preview and Start within your Plan’s limit. Preview alone keeps a hold. See migration 34 for the different behavior and re-upgrade risks of releases from before this migration.

Getting more help

If this guide does not solve the problem, ask in GitHub Discussions. Search earlier answers first. To report a bug, open an issue with the bug report form. Discussions and issues are public: do not include event content, calendar IDs, email addresses, credentials, or unredacted logs. If you cannot use GitHub, email support@calendarghost.com. Report security vulnerabilities privately, as SECURITY.md describes.

This page is built from docs/troubleshooting.md; edit it on GitHub.