Debugging

Understanding cloud logs:

If you get a cloud refusal code and need concrete remediation steps, see Common Update Problems.

Capgo logs can include metadata for the event. In the dashboard, use the action filter to filter by the snake_case action code listed below, and click the metadata cell to copy the full JSON payload. Metadata is especially useful for crash and WebView events because it can include context such as the error message, source URL, line and column, process state, memory pressure, or platform-specific reason. Older logs can still show the legacy camelCase aliases listed in parentheses.

Sent from the backend

code	Description
invalid_ip (InvalidIp)	The user is located in a Google data center and the update is less than 4 hours old. This is done to prevent Google bots’ devices from counting as devices in your account.
need_plan_upgrade (needPlanUpgrade, previously needUpgrade)	Indicates that you have reached the limit of your plan, and the device will not receive updates until you upgrade or until the next month.
no_new_version_available (noNew)	The device has the latest available version.
semver_error	The native version does not follow the expected semantic version format.
disabled_platform_ios (disablePlatformIos)	The device is on the iOS platform, but that is disabled in the channel settings.
disabled_platform_android (disablePlatformAndroid)	The device is on the Android platform, but that is disabled in the channel settings.
disable_auto_update (disableAutoUpdate)	Auto-update is disabled by compatibility policy. Metadata includes auto_update with a matching rule such as major, minor, patch, metadata, or none.
disable_auto_update_under_native (disableAutoUpdateUnderNative)	The device has version (1.2.3), and the channel has an update (1.2.2) under the device version to send, but that is disabled in the channel settings.
disable_dev_build (disableDevBuild)	The device has a dev build, but that is disabled in the channel settings.
disable_emulator (disableEmulator)	The device is an emulator, but that is disabled in the channel settings.
cannot_get_bundle (cannotGetBundle)	Failed to generate a valid signed URL for the bundle download. This occurs when the bundle URL generation fails or returns an invalid URL and there is no manifest available as a fallback.
cannot_update_via_private_channel (cannotUpdateViaPrivateChannel)	The device tried to self-associate with a private channel, but the channel settings do not allow device self-association (allow_device_self_set is false) and the channel is not public.
misconfigured_channel (channelMisconfigured)	The channel is configured to disable auto-update by version number (disable_auto_update: 'version_number'), but the bundle’s min_update_version field is null, making it impossible to determine which devices should receive the update.
disable_auto_update_to_metadata (disableAutoUpdateMetadata)	Auto-update is disabled by version number metadata. The channel requires the device’s version to be at least min_update_version, but the device’s current version is lower than this threshold.
disable_auto_update_to_major (disableAutoUpdateToMajor)	Channel setting disable_auto_update: 'major' prevents updates that would increase the major version number, such as blocking 1.x.x from updating to 2.x.x.
disable_auto_update_to_minor (disableAutoUpdateToMinor)	Channel setting disable_auto_update: 'minor' prevents updates that would increase the minor version number, such as blocking 1.2.x from updating to 1.3.x.
disable_auto_update_to_patch (disableAutoUpdateToPatch)	Channel setting disable_auto_update: 'patch' prevents updates that would increase the patch version number, or allows only patch-level updates within the same major.minor version.
missing_bundle (missingBundle)	The bundle assigned to this channel has no downloadable content. This means the bundle has no external_url, no r2_path, it is not a built-in version, and there are no manifest entries available for download.
no_channel (NoChannelOrOverride)	No default channel is configured for this app and the device has no specific channel override assigned. At least one must be present for updates to work.
rate_limited (rateLimited)	The device has been rate limited due to excessive requests.
key_id_mismatch (keyMismatch)	The device’s encryption public key does not match the public key used to encrypt the bundle. Metadata includes device_key_id, bundle_key_id, and version to help identify the mismatch.

Sent from the device

code	Description
ping	Internal test action used to verify the stats system is working correctly.
get	Info for downloading the new version has been sent to the device.
delete	One bundle has been deleted on the device.
set	A bundle has been set on the device.
set_fail	The bundle failed to set.
reset	The device reset to the builtin bundle.
download_XX	A new bundle has been downloaded - progress indicated by XX% (increments of 10%).
download_complete	The new bundle has finished downloading.
download_manifest_start	The device started downloading the update manifest.
download_manifest_complete	The device finished downloading the update manifest.
download_zip_start	The device started downloading the bundle archive.
download_zip_complete	The device finished downloading the bundle archive.
download_manifest_file_fail	One manifest entry failed to download; the stats payload puts version_name in the form version:fileName to pinpoint the asset.
download_manifest_checksum_fail	The manifest file failed checksum validation.
download_manifest_brotli_fail	The manifest file failed to decompress using Brotli.
download_fail	The new bundle failed to download.
update_fail	The new bundle has been installed but failed to call notifyAppReady.
checksum_fail	The new bundle failed to validate the checksum. This can happen for several reasons: 1) Checksum type mismatch: The latest version of the CLI and plugins (version 5.10.0+, 6.25.0+ or 7+) use SHA256 checksums, while older plugins used CRC32. If you see a checksum fail, check if the checksum is CRC32 (a shorter hash) rather than SHA256. This usually indicates the bundle was uploaded with an old version of the CLI. Verify your bundle version in the Capgo dashboard - bundles created since version 5.10.0/6.25.0/7 should use SHA256. If you’re seeing CRC32 checksums, ensure you have the latest plugin version installed locally (the CLI checks your local plugin version to determine which checksum type to upload), then upgrade your CLI and re-upload the bundle. 2) Encryption key mismatch (on plugin versions below 8.3.0 or 5/6/7.38.0): On older plugin versions, if the device’s public key doesn’t match the key used to encrypt the bundle, the decryption will fail silently and cause a checksum failure. If you’re using encryption and see checksum_fail, verify that the public key in your app’s capacitor.config.json matches the private key used to upload the bundle. Upgrading to plugin version 8.3.0+ (or 5/6/7.38.0+) will give you a proper keyMismatch error from the server instead, making this issue easier to diagnose.
windows_path_fail	The zip has files who contain windows path who are illegal
canonical_path_fail	The path of files is not canonical
directory_path_fail	There is an error in the path of zip files
unzip_fail	unzip failed
low_mem_fail	Download failed because of low memory in the device
app_moved_to_background	The application entered the background state.
app_moved_to_foreground	The application entered the foreground state.
app_crash	The app reported a crash detected from the JavaScript or Capacitor layer. Metadata can include the message, stack, source, and active bundle context.
app_crash_native	The native layer reported a platform crash. Metadata can include platform, reason, stack, and process details when available.
app_anr	Android reported an Application Not Responding event. Metadata can include the ANR reason, thread, or trace summary when available.
app_killed_low_memory	The app process was killed after low-memory pressure. Metadata can include available memory and platform signals when available.
app_killed_excessive_resource_usage	The OS killed the app for excessive resource use. Metadata can include the resource type or platform reason when available.
app_initialization_failure	The updater or app startup flow failed before normal runtime was ready. Metadata can include the failing step and error message.
app_memory_warning	iOS reported a memory warning. Metadata can include the active bundle and memory context when available.
webview_javascript_error	The WebView reported an uncaught JavaScript error. Metadata can include the message, source URL, line, column, and stack.
webview_unhandled_rejection	The WebView reported an unhandled promise rejection. Metadata can include the rejection reason, source URL, and stack.
webview_resource_error	A WebView resource failed to load. Metadata can include the URL, status code, resource type, and error message.
webview_security_policy_violation	The WebView reported a content security policy violation. Metadata can include the blocked URI, directive, and document URL.
webview_unclean_restart	The app detected a previous WebView session that did not shut down cleanly. This can help identify crash loops after an update.
webview_render_process_gone	Android reported that the WebView renderer process exited. Metadata can include whether the renderer crashed and the renderer priority.
webview_content_process_terminated	iOS reported that the WebView content process terminated. Metadata can include the active bundle and page URL when available.
decrypt_fail	Failed to decrypt the downloaded bundle.
get_channel (getChannel)	The current channel for the device was queried.
set_channel (setChannel)	A channel was successfully set for the device.
uninstall	The application was uninstalled or Capgo data cleared.
blocked_by_server_url	Server.url is present in your capacitor config, this make Capacitor serve remote url and ignore local files, while our updater is made to function with local file, Server.url Is consider by Capacitor Makers as bad practice in production and will lead to many issue and plugin not working correctly.

Bundle status

• SUCCESS: install bundle done
• ERROR: install or download failed
• PENDING: Download done, pending release
• DELETED: Bundle deleted, still presented for stats
• DOWNLOADING: Currently downloading a bundle

Understanding device logs:

Debug command:

There is a debug command for Capgo cloud users.

npx @capgo/cli@latest app debug

This will allow you to check all events happening in the app and find a solution if updates don’t happen.

IOS

to find your logs on Xcode

Getting the Device Log in Xcode

Android:

to find your logs on Android studio

View logs with Logcat

Explanations Logs

• Failed to download from => same as download_fail
• notifyAppReady was not called, roll back current bundle => same as as update_fail

Finding the downloaded bundle in your device

iOS

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

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

Did you know?

On Android, all versions are stored in one folder, unlike IOS where it has to be duplicated in two locations.

Understanding ios production crash logs

How to review your app's crash logs