Troubleshooting
Start with the symptom, check likely causes in order, and find the next action.
Updated 2026-09-14
On this page
- Find the last successful stage
- No update received
- Downloaded, but the old screen remains
- Rollback or blank screen after launch
- CLI waits, cannot authenticate or cannot find the app
- Common questions
- Is Expo Go supported?
- Which changes need a new native package?
- Does update.json ship in the app?
- Does pausing or deleting a deployment undo installed updates?
- How do I self-host?
- Does OTA guarantee store approval?
- If you still need help
Find the last successful stage
Record the native version, hash, channel, device ID and time. Do not start by reinstalling: it clears local update state and can hide the problem.
No update received
Check in order, retrying after each fix:
| Order | Check | If it fails |
|---|---|---|
| 1 | Release build starts without Metro | Reconnect native loading and rebuild |
| 2 | SDK appKey matches CLI application and platform | Run pakta me and compare configuration |
| 3 | The exact installed native build is registered | Upload that artifact, not a rebuild |
| 4 | Channel and native version match an active target | Check native metadata; update name is not native version |
| 5 | Application, channel, native package and deployment are active | Inspect pause and expiration states |
| 6 | The device is eligible for the percentage | Verify at 100% in a separate test app; production non-selection can be expected |
| 7 | Update endpoints and artifact URLs are reachable | Check SDK /api and CLI host separately |
bundleStatus: unknownBundle indicates baseline mismatch; republishing does not fix registration. rebuiltSameJs means identical JS with a different build identity and permits full fallback. See CheckResult.
Downloaded, but the old screen remains
download_success means download completion only. With silentAndLater, fully end the process after download and launch again. Backgrounding and resuming normally triggers another check.
If currentHash changed but the label did not, verify the .ppk entry point, branch and contents. A new release name does not prove new content.
Rollback or blank screen after launch
Stop expanding the rollout and retain the failing package and sourcemap. Read isRolledBack, rolledBackVersion and currentVersion from getUpdateMetadata() and restore the stack.
An unconfirmed update can be rolled back on a later launch. Errors after health confirmation do not necessarily trigger rollback. Redeploy a stable historical package and review critical initialization and confirmation timing.
CLI waits, cannot authenticate or cannot find the app
Check identity with
me; setRNU_SERVICE_URLbefore self-hosted login because credentials are isolated by service.Run from the app root containing
update.json; locally useselectApp --platform android.CI needs
PAKTA_API_TOKEN, explicit targets and--no-interactive, not selection prompts.For unknown options see CLI reference. Commit the lockfile for consistent local and CI versions.
Common questions
Is Expo Go supported?
No. Use a build containing native modules; follow Expo integration.
Which changes need a new native package?
Native dependencies, permissions, native code and runtime changes. OTA only delivers compatible JS/assets. See boundaries.
Does update.json ship in the app?
The CLI stores appId/appKey there. If business code imports it, contents enter the bundle; otherwise it is publishing configuration only. Never store publishing tokens in it.
Does pausing or deleting a deployment undo installed updates?
No. It changes future delivery. Installed content needs a recovery deployment and device activation. Reducing the percentage does not actively roll devices back either.
How do I self-host?
See self-hosting setup. Quotas depend on server configuration; do not assume unlimited usage.
Does OTA guarantee store approval?
No. Technical capability is not review permission. Apple restricts downloaded executable code that changes functionality; check the official review guidelines. Channel isolation is not a guarantee of avoiding review requirements.
If you still need help
Include platform, RN/Expo/SDK/CLI versions, native version, channel, current hash, deployment ID, failing stage, time and a sanitized stack. Exclude tokens, passwords and session configuration.