# Troubleshooting

Start with the symptom, check likely causes in order, and find the next action.

## Find the last successful stage {#technical}

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 {#no-update}

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](/docs/api#check-result).

## Downloaded, but the old screen remains {#activation}

`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 {#rollback}

Stop expanding the rollout and retain the failing package and sourcemap. Read `isRolledBack`, `rolledBackVersion` and `currentVersion` from `getUpdateMetadata()` and [restore the stack](/docs/errors).

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](/docs/publish#rollback) and review critical initialization and confirmation timing.

## CLI waits, cannot authenticate or cannot find the app {#cli}

- Check identity with `me`; set `RNU_SERVICE_URL` before self-hosted login because credentials are isolated by service.
- Run from the app root containing `update.json`; locally use `selectApp --platform android`.
- CI needs `PAKTA_API_TOKEN`, explicit targets and `--no-interactive`, not selection prompts.
- For unknown options see [CLI reference](/docs/cli). Commit the lockfile for consistent local and CI versions.

## Common questions {#business}

### Is Expo Go supported?

No. Use a build containing native modules; follow [Expo integration](/docs/getting-started#expo).

### Which changes need a new native package?

Native dependencies, permissions, native code and runtime changes. OTA only delivers compatible JS/assets. See [boundaries](/docs/introduction#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](/docs/getting-started#self-host). 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](https://developer.apple.com/app-store/review/guidelines/#software-requirements). Channel isolation is not a guarantee of avoiding review requirements.

## If you still need help {#support}

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.