Introducing LiveActivityRead more

Guides / TroubleshootingMenu

Troubleshooting

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

Updated · Markdown · Ask Claude · Ask ChatGPT

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 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 with the activity ID.