Debugging
Copy a setup prompt with the install steps and the full markdown guide for this plugin.
Understanding cloud logs
Section titled âUnderstanding cloud logsâIf you get a cloud refusal code and need deeper remediation walkthroughs, see Common Update Problems.
Capgo logs can include metadata for the event. In the dashboard, filter by the snake_case action code, and click the metadata cell to copy the full JSON payload. Metadata is especially useful for crash and WebView events because it can include the error message, source URL, line and column, process state, memory pressure, or platform-specific reason. Older logs can still show legacy camelCase aliases listed in parentheses.
Each section title matches the action code shown in the console logs table, so you can link directly to it.
Plan limits and normal responses
Section titled âPlan limits and normal responsesâBackend refusals related to billing, throttling, or non-error states.
InvalidIp
Section titled âInvalidIpâWhat it means
Capgo detected traffic that looks like it comes from Google or cloud infrastructure. Updates less than four hours old are ignored so bot traffic does not count as billable devices.
What to do
Ignore this on real users. Retry from normal networks and real devices, or wait and check again later.
needPlanUpgrade
Section titled âneedPlanUpgradeâWhat it means
Your organization reached its plan or device limit. The device will not receive updates until you upgrade or the next billing cycle resets usage.
What to do
Upgrade your plan in the dashboard or wait for the next billing cycle.
What it means
The device already has the latest bundle available for its channel. This is a normal state, not a failure.
rateLimited
Section titled ârateLimitedâWhat it means
The device sent too many update or channel requests in a short window.
What to do
Stop calling update APIs inside render loops. Call setChannel / getChannel only from user actions, and set defaultChannel in capacitor.config.
Version format
Section titled âVersion formatâBackend refusals caused by invalid native version metadata.
semver_error
Section titled âsemver_errorâWhat it means
The native app version in config is missing or not valid semver (x.y.z).
What to do
Set plugins.CapacitorUpdater.version to valid semver, verify it in the SemVer tester, then rebuild and reinstall the native app.
Platform and build targeting
Section titled âPlatform and build targetingâBackend refusals when channel policy blocks a platform, build type, or device class.
disablePlatformIos
Section titled âdisablePlatformIosâWhat it means
The device runs iOS, but iOS updates are disabled for this channel.
What to do
Enable iOS in the channel if this was accidental, or route iOS builds to a dedicated channel when blocking is intentional.
disablePlatformAndroid
Section titled âdisablePlatformAndroidâWhat it means
The device runs Android, but Android updates are disabled for this channel.
What to do
Enable Android in the channel if this was accidental, or route Android builds to a dedicated channel when blocking is intentional.
disablePlatformElectron
Section titled âdisablePlatformElectronâWhat it means
The device runs Electron, but Electron updates are disabled for this channel.
What to do
Enable Electron in the channel if this was accidental, or route Electron builds to a dedicated channel when blocking is intentional.
disableDevBuild
Section titled âdisableDevBuildâWhat it means
The device is a development build, but dev builds are blocked for this channel.
What to do
Allow dev builds in a test channel, or keep this channel release-only and move dev devices elsewhere.
disableProdBuild
Section titled âdisableProdBuildâWhat it means
A production build called /updates, but production updates are blocked for this channel.
What to do
Allow production updates in the channel if this was accidental, or route production builds to the correct channel.
disableDevice
Section titled âdisableDeviceâWhat it means
A real phone or tablet was blocked because this channel blocks real devices.
What to do
Enable real-device updates if this was accidental, or keep the restriction and route real devices to another channel.
disableEmulator
Section titled âdisableEmulatorâWhat it means
The device is an emulator, but emulator updates are disabled for this channel.
What to do
Enable emulator updates in a test channel, or keep this channel emulator-blocked and use another channel for emulator validation.
Auto-update compatibility rules
Section titled âAuto-update compatibility rulesâBackend refusals when semver or metadata rules block the target bundle.
disableAutoUpdate
Section titled âdisableAutoUpdateâWhat it means
Auto-update is disabled by channel compatibility policy. Metadata includes auto_update with a matching rule such as major, minor, patch, metadata, or none.
What to do
Change the channel auto-update policy to allow your intended rollout.
disableAutoUpdateUnderNative
Section titled âdisableAutoUpdateUnderNativeâWhat it means
The channel has a bundle older than the device baseline and blocks sending updates under the native version.
What to do
Publish a bundle at or above the native baseline, or disable under-native protection in the channel.
disableAutoUpdateMetadata
Section titled âdisableAutoUpdateMetadataâWhat it means
The channel requires min_update_version, but the device native version is below that threshold.
What to do
Set min_update_version on the target bundle or release from a newer native version.
disableAutoUpdateToMajor
Section titled âdisableAutoUpdateToMajorâWhat it means
The channel blocks major version jumps, for example 1.x.x to 2.x.x.
What to do
Align channel strategy with your major rollout plan, or allow major jumps for this track. See Common Update Problems.
disableAutoUpdateToMinor
Section titled âdisableAutoUpdateToMinorâWhat it means
The channel blocks minor version jumps relative to the device native baseline (version_build), for example 1.2.3 to 1.3.0.
What to do
Align channel strategy with your minor rollout plan, or allow minor jumps for this track.
disableAutoUpdateToPatch
Section titled âdisableAutoUpdateToPatchâWhat it means
The channel blocks patch-level changes while keeping the same MAJOR.MINOR.PATCH prefix; only suffix changes are allowed.
What to do
Align release cadence with channel policy, or allow patch jumps for this track.
Channel setup
Section titled âChannel setupâBackend refusals caused by missing or incompatible channel configuration.
cannotUpdateViaPrivateChannel
Section titled âcannotUpdateViaPrivateChannelâWhat it means
The device tried to self-associate with a private channel that does not allow device self-assignment (allow_device_self_set is false) and the channel is not public.
What to do
Enable allow_device_self_set on the channel or switch the device to a public or allowed channel.
channelMisconfigured
Section titled âchannelMisconfiguredâWhat it means
The channel uses disable_auto_update: "version_number" but the bundle min_update_version is null, so Capgo cannot decide which devices should update.
What to do
Fill the missing config for that rule or switch to a simpler auto-update mode.
NoChannelOrOverride
Section titled âNoChannelOrOverrideâWhat it means
No default channel is configured and the device has no channel override.
What to do
Set a default channel in the dashboard or configure defaultChannel in the build.
Bundle delivery and encryption
Section titled âBundle delivery and encryptionâBackend refusals when Capgo cannot serve or decrypt the bundle.
cannotGetBundle
Section titled âcannotGetBundleâWhat it means
Capgo failed to generate a valid signed download URL and no manifest fallback was available.
What to do
Re-upload the bundle, regenerate manifests, and verify R2 or public bundle settings.
missingBundle
Section titled âmissingBundleâWhat it means
The bundle assigned to the channel has no downloadable content: no external_url, no r2_path, not a built-in version, and no manifest entries.
What to do
Rebuild and re-upload the version, then confirm the bundle has real file content.
keyMismatch
Section titled âkeyMismatchâWhat it means
The device encryption public key does not match the key used to encrypt the bundle. Metadata can include device_key_id, bundle_key_id, and version.
What to do
Compare device and bundle key IDs in the console. Publish with the same key and matching CLI/plugin versions.
App configuration and legacy clients
Section titled âApp configuration and legacy clientsâBackend refusals caused by app configuration or unsupported updater versions.
customIdBlocked
Section titled âcustomIdBlockedâWhat it means
The app sent a custom device ID, but this app does not accept custom IDs, so the ID is ignored.
What to do
Stop sending custom IDs, or enable custom IDs only when your workflow requires them.
blocked_by_server_url
Section titled âblocked_by_server_urlâWhat it means
server.url is set in Capacitor config, so the WebView loads a remote URL instead of local bundle files. Capgo live updates require local files and server.url is discouraged in production.
What to do
Remove or clear server.url for production builds and keep update payloads local. This code can appear as a backend refusal or as a device-side stat.
backend_refusal
Section titled âbackend_refusalâWhat it means
The updater plugin is v4, which the backend no longer accepts.
What to do
Upgrade plugin and CLI to v5+ (prefer v8) with Capacitor v5+, rebuild, and republish bundle metadata.
Update lifecycle
Section titled âUpdate lifecycleâDevice-side events for normal update flow, activation, and rollback.
What it means
Internal test action used to verify the stats pipeline.
What it means
Capgo sent download information for a new version to the device.
What it means
A bundle was activated on the device.
set_fail
Section titled âset_failâWhat it means
A bundle failed to activate on the device.
What to do
Check native logs with npx @capgo/cli@latest app debug and verify bundle integrity, paths, and notifyAppReady flow.
What it means
The device reset to the built-in bundle.
What it means
One bundle was deleted on the device.
Download and install failures
Section titled âDownload and install failuresâDevice-side events for download progress, archive validation, and install errors.
download_0
Section titled âdownload_0âWhat it means
The download sequence started at 0% progress.
download_10
Section titled âdownload_10âWhat it means
A new bundle has been downloaded â progress indicated at 10%.
download_20
Section titled âdownload_20âWhat it means
A new bundle has been downloaded â progress indicated at 20%.
download_30
Section titled âdownload_30âWhat it means
A new bundle has been downloaded â progress indicated at 30%.
download_40
Section titled âdownload_40âWhat it means
A new bundle has been downloaded â progress indicated at 40%.
download_50
Section titled âdownload_50âWhat it means
A new bundle has been downloaded â progress indicated at 50%.
download_60
Section titled âdownload_60âWhat it means
A new bundle has been downloaded â progress indicated at 60%.
download_70
Section titled âdownload_70âWhat it means
A new bundle has been downloaded â progress indicated at 70%.
download_80
Section titled âdownload_80âWhat it means
A new bundle has been downloaded â progress indicated at 80%.
download_90
Section titled âdownload_90âWhat it means
A new bundle has been downloaded â progress indicated at 90%.
download_complete
Section titled âdownload_completeâWhat it means
The bundle download finished successfully.
download_manifest_start
Section titled âdownload_manifest_startâWhat it means
The device started downloading the update manifest.
download_manifest_complete
Section titled âdownload_manifest_completeâWhat it means
The device finished downloading the update manifest.
download_zip_start
Section titled âdownload_zip_startâWhat it means
The device started downloading the bundle archive.
download_zip_complete
Section titled âdownload_zip_completeâWhat it means
The device finished downloading the bundle archive.
download_manifest_file_fail
Section titled âdownload_manifest_file_failâWhat it means
One manifest entry failed to download. version_name uses version:fileName to identify the asset.
What to do
Fix the missing or blocked asset, regenerate the manifest, and re-upload the bundle.
download_manifest_checksum_fail
Section titled âdownload_manifest_checksum_failâWhat it means
A manifest file failed checksum validation.
What to do
Re-upload the bundle with a current CLI version and verify manifest checksums.
download_manifest_brotli_fail
Section titled âdownload_manifest_brotli_failâWhat it means
A manifest file failed Brotli decompression.
What to do
Verify compression settings and re-upload affected assets.
download_fail
Section titled âdownload_failâWhat it means
The bundle failed to download.
What to do
Check network connectivity, signed URL expiry, CDN reachability, and device storage.
update_fail
Section titled âupdate_failâWhat it means
The bundle installed but the app never called notifyAppReady, so Capgo rolled back.
What to do
Call notifyAppReady() after your app finishes bootstrapping. Native log text notifyAppReady was not called, roll back current bundle maps to this code.
checksum_fail
Section titled âchecksum_failâWhat it means
The downloaded bundle failed checksum validation. Common causes: CRC32 vs SHA256 mismatch from an old CLI upload, or encryption key mismatch on older plugins that surface decryption failure as checksum failure.
What to do
Re-upload with a current CLI/plugin (SHA256). If using encryption, verify the app public key matches the upload key, or upgrade to plugin 8.3.0+ for explicit keyMismatch errors.
decrypt_fail
Section titled âdecrypt_failâWhat it means
The downloaded bundle failed to decrypt.
What to do
Verify encryption keys and re-upload the bundle with the matching key pair.
windows_path_fail
Section titled âwindows_path_failâWhat it means
The zip contains illegal Windows-style paths.
What to do
Rebuild the bundle on Unix paths or sanitize archive paths before upload.
canonical_path_fail
Section titled âcanonical_path_failâWhat it means
File paths inside the zip are not canonical.
What to do
Fix archive path generation before upload.
directory_path_fail
Section titled âdirectory_path_failâWhat it means
The zip contains invalid directory paths.
What to do
Fix archive structure before upload.
unzip_fail
Section titled âunzip_failâWhat it means
The device failed to unzip the downloaded bundle.
What to do
Verify archive integrity and supported compression.
low_mem_fail
Section titled âlow_mem_failâWhat it means
Download failed because the device ran out of memory.
What to do
Reduce bundle size or retry on a device with more free memory.
App health and WebView events
Section titled âApp health and WebView eventsâDevice-side crash, memory, and WebView diagnostics. Always inspect metadata JSON in the dashboard.
app_moved_to_background
Section titled âapp_moved_to_backgroundâWhat it means
The app entered the background.
app_moved_to_foreground
Section titled âapp_moved_to_foregroundâWhat it means
The app entered the foreground.
app_crash
Section titled âapp_crashâWhat it means
JavaScript or Capacitor layer crash. Metadata can include message, stack, source, and active bundle context.
What to do
Inspect metadata and native logs. Pair JS and native error reporting (for example Sentry) to locate the failing code path.
app_crash_native
Section titled âapp_crash_nativeâWhat it means
Native platform crash. Metadata can include platform, reason, stack, and process details.
What to do
Use Xcode or Logcat crash logs and correlate with the active bundle from metadata.
app_anr
Section titled âapp_anrâWhat it means
Android Application Not Responding event.
What to do
Inspect ANR traces in Logcat and reduce main-thread blocking work after updates.
app_killed_low_memory
Section titled âapp_killed_low_memoryâWhat it means
The OS killed the app after memory pressure.
What to do
Reduce memory use after update activation and inspect metadata for available memory signals.
app_killed_excessive_resource_usage
Section titled âapp_killed_excessive_resource_usageâWhat it means
The OS killed the app for excessive resource use.
What to do
Inspect metadata for the resource type or platform reason.
app_initialization_failure
Section titled âapp_initialization_failureâWhat it means
Updater or startup failed before normal runtime was ready.
What to do
Inspect metadata for the failing step and error message.
app_memory_warning
Section titled âapp_memory_warningâWhat it means
iOS memory warning.
What to do
Inspect memory context in metadata and reduce peak usage after updates.
webview_javascript_error
Section titled âwebview_javascript_errorâWhat it means
Uncaught JavaScript error in the WebView. Metadata can include message, source URL, line, column, and stack.
What to do
Install error reporting in JS and native layers to capture the exact failing line in production.
webview_unhandled_rejection
Section titled âwebview_unhandled_rejectionâWhat it means
Unhandled promise rejection in the WebView.
What to do
Capture async failures with JS and native error reporting.
webview_resource_error
Section titled âwebview_resource_errorâWhat it means
A WebView resource failed to load.
What to do
Use metadata URL and status details to fix broken assets or network rules.
webview_security_policy_violation
Section titled âwebview_security_policy_violationâWhat it means
Content security policy blocked a resource.
What to do
Adjust CSP using metadata directive and blocked URI details.
webview_unclean_restart
Section titled âwebview_unclean_restartâWhat it means
Previous WebView session did not shut down cleanly, which can indicate crash loops after an update.
What to do
Correlate with crash and WebView error events before and after restart.
webview_render_process_gone
Section titled âwebview_render_process_goneâWhat it means
Android WebView renderer process exited.
What to do
Inspect renderer crash signals in metadata and native logs.
webview_content_process_terminated
Section titled âwebview_content_process_terminatedâWhat it means
iOS WebView content process terminated.
What to do
Inspect active bundle and page URL from metadata.
Environment and channel context
Section titled âEnvironment and channel contextâDevice-side context events that help correlate update behavior with OS, native version, or channel changes.
os_version_changed
Section titled âos_version_changedâWhat it means
Device OS version changed between checks.
native_app_version_changed
Section titled ânative_app_version_changedâWhat it means
Native app store version changed, helping separate native vs web bundle changes.
getChannel
Section titled âgetChannelâWhat it means
The device queried its current channel.
setChannel
Section titled âsetChannelâWhat it means
A channel was set successfully for the device.
uninstall
Section titled âuninstallâWhat it means
The app was uninstalled or Capgo data was cleared.
Bundle status
Section titled âBundle statusâSUCCESS: install bundle doneERROR: install or download failedPENDING: Download done, pending releaseDELETED: Bundle deleted, still presented for statsDOWNLOADING: Currently downloading a bundle
Understanding device logs
Section titled âUnderstanding device logsâDebug command
Section titled âDebug commandâThere is a debug command for Capgo cloud users.
npx @capgo/cli@latest app debugThis will allow you to check all events happening in the app and find a solution if updates donât happen.
iOS native logs
Section titled âiOS native logsâto find your logs on Xcode
Android native logs
Section titled âAndroid native logsâto find your logs on Android studio
Native log phrase mapping
Section titled âNative log phrase mappingâFailed to download frommaps todownload_failnotifyAppReady was not called, roll back current bundlemaps toupdate_fail
Finding the downloaded bundle on a device
Section titled âFinding the downloaded bundle on a deviceâTo debug on iOS, you need to dump the app on your computer, you can do it like this:
Xcode has a built-in feature for inspecting the file system of developer-installed apps on an iOS device.
To achieve this:
- Connect your device to your Mac and select Window > Devices in the Xcode menubar.
- Select your device in the left pane under the Devices section.
- This will show a list of developer-installed apps for that device.
- Select the app you want to inspect and then select the 3 dots icon near the bottom of the screen.
- Here you can view the current file system by selecting download a snapshot of it.
Selecting Download Container⌠will download and export a snapshot of the file system as a .xcappdata file that you can browse through.
Right-click on this file and select Show Package Contents to open the folder.
Open the App Data folder, and you should now see a few folders like Documents, Library, tmp, etc.
Then you will find a version in 2 folders:
library/NoCloud/ionic_built_snapshots is necessary after the app reboot
and documents/versions for hot reload
Android
Section titled âAndroidâTo debug on Android, you need to access the device from Android Studio:
- Click View > Tool Windows > Device File Explorer or click the Device File Explorer button in the tool window bar to open the Device File Explorer.
- Select a device from the dropdown list.
- Open the path data/data/APP_NAME/ where APP_NAME is your app ID.
Then Find the versions folder to see all the versions
Understanding ios production crash logs
Section titled âUnderstanding ios production crash logsâKeep going from Debugging
Section titled âKeep going from DebuggingâIf you are using Debugging to plan native plugin work, connect it with Using @capgo/capacitor-updater for the native capability in Using @capgo/capacitor-updater, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.