# Troubleshooting

> Updates not arriving, push-to-start not working, and how to read the activity timeline.

Updated 2026-11-21

Open the activity under **Activities** in the dashboard first. Its timeline shows every push we sent, what Apple
answered, and what the phone reported. Most problems are visible there.

## Updates don't arrive

**You get a 422.** The `contentState` doesn't fit what the app's `ContentState` sends: a key the app doesn't have, a
value of another JSON type, or a push over 4096 bytes. iOS would drop such a push without a word, so we refuse it
instead. The error names the first difference. Fix the keys and types, or the app's struct. See the
[API reference](/docs/api#422-and-the-content-state). Also check dates: Swift's default `Codable` encodes `Date` as
seconds since 2001, so send numbers your struct expects ([Swift SDK](/docs/swift#dates-in-the-content-state)).

**The activity has no update token.** Every activity has its own update token, reported by the SDK once the activity is
on the phone. Without it we can't update that device. In the activity's devices, `hasPushToken` is `false`. Check that:

- the app called `configure` and `register` at launch (in `App.init`, not in a view), so reports also work after a
  background launch,
- the phone had network access, since the SDK reports tokens over the network.

A device that gets its token late catches up on the latest state by itself.

**Apple refused it, or the token is stale.** The timeline shows "Apple refused the update push" with Apple's reason.
If Apple says the token is invalid (`BadDeviceToken`, `Unregistered`, `DeviceTokenNotForTopic`, or status 410), we stop
using that token and send a `token.invalid` webhook. Such a token won't work again. Start a new activity. Apple can also answer with a retryable error (status 429, 5xx or an expired
provider token), and we retry the push.

**Sandbox and production don't match.** See below.

**Too many updates with an alert.** Updates go at priority 5. An update with an `alert` goes at priority 10, which
counts against Apple's hourly budget for Live Activities. Leave out `alert` for
routine progress updates and use it for the moments that deserve attention. Rapid updates also collapse into the newest
one, so the phone can skip intermediate states.

**The activity has ended.** Updating one that has ended, been cancelled or failed returns `409`.

## Push-to-start doesn't work

**The phone is below iOS 17.2.** Push-to-start needs iOS 17.2. Below it the SDK reports no push-to-start token. You can
still start activities in the app with `start` and update them from your backend.

**No push-to-start token is registered.** The activity becomes `failed` and the timeline says "No push-to-start token
for this user and attributes type" (webhook `delivery.failed`, error `no_push_to_start_token`). Check that:

- the app ran on a **real device** (the Simulator doesn't issue tokens) and called `LiveActivity.configure` and
  `register(YourAttributes.self)` at launch,
- the `attributesType` you send is the Swift struct name, exactly (`DeliveryAttributes`),
- the `userId` you send is the one the app passed to `identify(userId:)`. Until then the install has no user. You can
  also target one install with `installId`,
- the app's page in the dashboard shows the device under **Devices**.

**Sandbox and production don't match.** Each app in the dashboard has one APNs environment. Tokens from builds run from
Xcode are sandbox tokens, and tokens from TestFlight and the App Store are production tokens. Sent to the wrong one,
Apple refuses them (usually as `BadDeviceToken`). Set the app's environment to match the build, or add a second app
for the other one. The bundle ID, Team ID and `.p8` key must also belong to the app you build.

**The app also needs** the Push Notifications capability and `NSSupportsLiveActivities` set to `YES`.

**A scheduled start on iOS 26 shows nothing.** On iOS 26 the phone starts the activity itself at `startAt`. If it hasn't
reported it 60 seconds later, we send a push-to-start instead, and the timeline shows "The phone didn't start it on
time". A push-to-start token is needed for that fallback.

## Read the timeline

Each entry is something we sent, got from Apple, or got from the phone. In the API they are the `events` of
`GET /activities/:id`.

| Timeline entry | Event type | Meaning |
|---|---|---|
| Scheduled from your backend / by the app | `scheduled` | The start is queued for `startAt`. |
| Apple accepted / refused the start push | `apns.start` | `detail.status` is Apple's HTTP status, `detail.reason` its reason. `200` means accepted. |
| Apple accepted / refused the update push | `apns.update` | Same, with the `version` pushed. |
| Apple accepted / refused the end push | `apns.end` | Same. |
| On the phone | `sdk.active` | The device reports the activity as running. |
| Device is preparing it | `sdk.pending` | The device is still preparing it. |
| Marked stale on the device | `sdk.stale` | The stale date passed without an update. |
| Ended on the device | `sdk.ended` | |
| The user dismissed it | `sdk.dismissed` | |
| Started in the app | `started_on_device` | The app started it locally and the SDK reported it. |
| The phone didn't start it on time | `local_start_missing` | An iOS 26 scheduled start didn't happen, we pushed instead. |
| Couldn't start | `failed` | No push-to-start token for the user and attributes type. |
| Start cancelled | `cancelled` | |
| Webhook: … | `webhook.<type>` | We queued that webhook for your endpoint. |

"Apple accepted the push" means APNs took it. It doesn't prove the phone showed it. If Apple accepted the push but nothing
changes, the content state may not decode on the device, or the activity may be gone. Compare the
`contentState` with the app's struct, and check for `sdk.ended` or `sdk.dismissed`.

If you can't tell from the timeline, write to [support@liveactivity.dev](mailto:support@liveactivity.dev) with the activity ID.
