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. Also check dates: Swift’s default Codable encodes Date as
seconds since 2001, so send numbers your struct expects (Swift SDK).
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
configureandregisterat launch (inApp.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.configureandregister(YourAttributes.self)at launch, - the
attributesTypeyou send is the Swift struct name, exactly (DeliveryAttributes), - the
userIdyou send is the one the app passed toidentify(userId:). Until then the install has no user. You can also target one install withinstallId, - 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 with the activity ID.