Troubleshooting

This page covers the most common issues encountered when setting up or running DeployPulse OTA updates, along with steps to diagnose and resolve them.

App Doesn't Receive Updates

Check the deployment key. The most common cause is a mismatched key.

dpctl deployment ls MyApp-iOS

Compare the key in your Info.plist / strings.xml against the key shown in the dashboard or CLI output. A single character difference will prevent devices from receiving updates.

Check if the release is disabled. A release can be disabled at upload time or patched to disabled afterward:

# Re-enable a disabled release
dpctl patch MyApp-iOS Production v5 --disabled false

Check targetBinaryVersion. A release only delivers to devices whose native app version matches. View this in the dashboard's release history or via:

dpctl deployment history MyApp-iOS Production

If the device's native version is 1.0.1 and the release targets 1.0.0, it will not be delivered.

Non-mandatory release not yet polled. Optional releases only download when the SDK polls. If checkFrequency is set to ON_APP_START (default), the device must be restarted. You can also trigger a check manually from your app code:

import codePush from 'react-native-code-push'
codePush.sync()

White or Black Screen After Update

This almost always means the bundle is incompatible with the running native binary.

• Wrong platform — an iOS bundle deployed to an Android device (or vice versa). DeployPulse requires separate apps per platform (MyApp-iOS, MyApp-Android). Confirm the platform field on the release in deployment history.
• Wrong target binary version — the updated bundle calls a native module API that does not exist in the device's installed binary. Check targetBinaryVersion on the release.

If Auto Rollback is enabled, a spike in error reports will trigger an automatic revert. See the Auto Rollback guide.

Update Downloads but Never Installs

installMode requires a restart. The default installMode is ON_NEXT_RESTART — the app must be backgrounded and then reopened before the update takes effect. Use IMMEDIATE for updates that should apply without a restart (the app will reload):

codePush.sync({ installMode: codePush.InstallMode.IMMEDIATE })

Code Signing mismatch. If a signingKey (public key) is configured on the app in DeployPulse, every release must be signed with the matching private key using --private-key. A release without a valid signature is silently rejected by the SDK. See the Code Signing guide.

Large Bundle Sizes or Slow Updates

• Source maps included in the release. Always pass --sourcemapOutput to a path outside --outputDir. Map files can double the bundle size.
• Dev bundle. Always pass --dev false for production releases. Dev bundles include the React Native DevTools bridge and are significantly larger.
• DeployPulse diff packages. Subsequent releases automatically send only files that changed since the previous release. Check the diff badge in the dashboard's release history to confirm diffs are being generated. No configuration is needed — diffs are computed automatically on the server.

See the Optimize Assets guide for a full list of bundle size reduction techniques.

CocoaPods Version Conflict (iOS)

If pod install fails with a minimum deployment target error after adding react-native-code-push, specify the iOS version at the top of your Podfile:

platform :ios, '13.0'

Then run pod install again.

Deployment Key Rotation Breaks Device Update Checks

After rotating a deployment key in the dashboard, existing app installs still send the old key and receive a 401 from the server — they will not receive updates until the user installs a new native build that contains the new key.

Recommended strategy: Before rotating a key, release a mandatory update to push a new native build to all devices first. Once the new binary (with the new key) has broad adoption, rotate the key. See the Quickstart for key configuration details.

Inspecting Logs on Android Test Devices

When an update isn't installing and the cause isn't obvious, the CodePush SDK logs its full decision flow to Android's system log. With a device connected via USB (USB debugging enabled), run:

adb logcat | grep -i codepush

This will stream lines like:

Common things to look for:

• No update available — the server responded but found no matching release. Double-check the deployment key and targetBinaryVersion.
• Invalid signature — a signing key is configured on the app but this release was not signed, or was signed with the wrong private key. See Code Signing.
• Network error or no output at all — the device can't reach the DeployPulse server. Check the serverUrl in strings.xml and verify network connectivity.
• installMode: ON_NEXT_RESTART (default) — the update downloaded successfully but won't apply until the app is backgrounded and reopened.

Inspecting Logs on iOS Simulator

The iOS Simulator routes native SDK output through macOS's Unified Logging System. With a simulator booted, stream and filter CodePush log lines from your terminal:

xcrun simctl spawn booted log stream --level debug | grep -i codepush

The --level debug flag is required — CodePush SDK messages are emitted at debug level and are suppressed without it.

You'll see output similar to:

2024-03-24 11:42:01.123 CodePushModule[1234:56789] Checking for update...
2024-03-24 11:42:01.456 CodePushModule[1234:56789] Update available: v7
2024-03-24 11:42:03.789 CodePushModule[1234:56789] Package installed successfully

Common things to look for:

• No output at all — the simulator may not be running, or the update check hasn't been triggered. Try backgrounding and reopening the app, or call codePush.sync() manually.
• Update check failed — the device can't reach the DeployPulse server. Verify the serverURL value in your Info.plist and check that the Simulator has network access.
• Invalid binary version — the release's targetBinaryVersion doesn't match the native app version in the Simulator. Check the version with dpctl deployment history MyApp-iOS Production.
• Package installed successfully but no change visible — the installMode is ON_NEXT_RESTART. Background and reopen the app.

Getting Help

• GitHub Issues — bug reports and feature requests
• Dashboard support link — available in the bottom-left corner of the DeployPulse dashboard
• Sentry Integration — symbolicated stack traces for crashes in OTA releases