> For the complete documentation index, see [llms.txt](https://docs.kinwall.family/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinwall.family/self-hosting-reference/troubleshooting.md).

# Troubleshooting

## Stale app after an update

Home Screen apps on iOS can keep an old version in memory.

1. On the affected device: **Settings → General → This display → Clear cache and reload**. It clears caches, re-checks the service worker and reloads from the network. You stay signed in.
2. Still stuck? Close the app from the app switcher and reopen it.
3. Last resort: delete the Home Screen icon and add it again. This signs the device out, so a display then needs pairing again.

Kinwall's service worker deliberately caches nothing, and the server sends `no-cache` for everything except hashed assets, so this should be rare.

## Setup code not accepted

* The code changes on every restart (Docker) until the instance is claimed. Use the latest one from the log.
* After 10 wrong attempts in an hour you'll see "too many attempts — try again later".
* You can always use `ADMIN_API_KEY` instead, via **Use your ADMIN\_API\_KEY instead**.

## Google/Outlook buttons are greyed out

No OAuth client is configured yet. Set one up under **Settings → Calendars → Calendar providers**. See [Google](/connecting-calendars/google.md) and [Microsoft](/connecting-calendars/microsoft.md).

## Google says `redirect_uri_mismatch`

The redirect URI registered with Google must match the one on the provider card exactly. Check **Public URL**: scheme, host, port, no trailing path. Google also rejects bare LAN IPs, so use HTTPS or `localhost`.

## Sync errors

The calendar's row in **Settings → Calendars** shows the last error.

| Error                                            | Fix                                                                                                          |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| "Calendar URL must be a public http(s) address…" | The feed or CalDAV server is on your LAN. See [Private / LAN feeds](/connecting-calendars/private-feeds.md). |
| "Reconnect this calendar to resume syncing"      | It came from an import. See [Reconnecting after import](/connecting-calendars/reconnecting-after-import.md). |
| 401 / invalid grant from Google or Microsoft     | The token was revoked or expired. Remove the account and **Connect** it again.                               |
| CalDAV authentication failed                     | For iCloud, use an app-specific password, not your Apple Account password.                                   |
| Worker CPU limit exceeded                        | The ICS feed is very large. See [Cloudflare specifics](/self-hosting-reference/cloudflare.md).               |

Old events stay visible after a failed sync. **Sync now** retries straight away.

## Push notifications not arriving

1. **iPhone/iPad**: iOS 16.4+, Kinwall added to the Home Screen and opened from there. Safari tabs can't receive push.
2. The device is listed under **Settings → Access → Notifications** (on an admin device). "never delivered" means the push service hasn't accepted a message for it yet.
3. **Send test** in **Settings → General → Notifications**. If the test arrives but reminders don't:
   * Is **Event reminders** on, and does **Which family members?** include the event's people?
   * Does the event have a reminder? Check the 🔔 line in its sheet, or the household **Default reminder**.
   * Summaries and nudges fire at the exact minute you set, in the household timezone. Check **Settings → General → Timezone**.
4. Check the OS notification settings for the browser or installed app, including Focus / Do Not Disturb.
5. If the device was removed from the list, its subscription expired. Turn notifications on again.
6. Docker: the notification loop runs every 2 minutes, but only while the container is running.

## A display shows an admin section, or doesn't

Settings shows the display view until the server confirms the device is an admin. If an admin phone only shows General and Family, it's signed in with a display key. Sign out and **Sign in with passkey**.

## Lost every passkey

Use **Use a recovery code** on the sign-in screen, or `ADMIN_API_KEY` via **Enter a key manually**. Then add a new passkey. See [Sign-in & security](/using-kinwall/sign-in-and-security.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kinwall.family/self-hosting-reference/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.