Troubleshooting

Here are some common issues you might encounter while using Capgo and how to resolve them.

Upload failures

If your bundle upload fails, double check:

• Your app ID in capacitor.config.ts matches your app in the Capgo dashboard
• You’re running the upload command from the root of your Capacitor project
• Your web assets are built and up to date

Advanced upload options

The Capgo CLI provides some additional flags to help with common upload issues:

• --tus: Uses the tus resumable upload protocol for more reliable uploads of large bundles or on poor network connections. If your bundle is over 10MB or you’re on a spotty connection, consider using --tus:

  npx @capgo/cli@latest upload --tus

• --package-json and --node-modules: Tells Capgo where to find your root package.json and node_modules if your app uses a non-standard structure like a monorepo or npm workspace. Pass the path to the root package.json and the --node_modules path:

  npx @capgo/cli@latest upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo needs this information to correctly bundle your app’s dependencies.

You can combine these flags with other options like --channel as needed. See the Capgo CLI docs for full details on the available upload options.

If you’re still having trouble with uploads, reach out to Capgo support for further assistance.

Debugging Updates

If you’re encountering issues with live updates, the Capgo debug command is a helpful tool for troubleshooting. To use it:

1. Run the following command in your project directory:

   npx @capgo/cli@latest app debug

2. Launch your app on a device or emulator and perform the action that should trigger an update (e.g. reopening the app after uploading a new bundle).

3. Watch the output of the debug command. It will log information about the update process, including:

   • When the app checks for an update
   • If an update is found and what version it is
   • Download and installation progress for the update
   • Any errors that occur during the update process

4. Use the debug logs to identify where the issue is occurring. For example:

   • If no update is found, double check that your bundle was uploaded successfully and the app is configured to use the correct channel.
   • If the update downloads but doesn’t install, make sure you’ve called CapacitorUpdater.notifyAppReady() and that the app was fully closed and reopened.
   • If you see an error message, look up that specific error in the Capgo docs or reach out to support for help.

The debug command is especially useful for identifying issues with the update download and installation process. If the logs show the expected update version was found but not ultimately applied, focus your troubleshooting on the steps after the download.

Debugging with Native Logs

In addition to the Capgo debug command, the native logs on Android and iOS can provide valuable troubleshooting information, especially for issues on the native side of the update process.

Android Logs

To access the Android logs:

1. Connect your device or start your emulator
2. Open Android Studio and select “View > Tool Windows > Logcat”
3. In the Logcat window, filter the logs to just your app’s process by selecting it from the dropdown at the top
4. Look for any lines that include Capgo to find the SDK logs

Alternatively, you can use the adb logcat command and grep for Capgo to filter the logs.

The Capgo SDK will log key events during the update process, such as:

• When an update check is initiated
• If an update is found and what version it is
• When the update download starts and completes
• When the update installation is triggered
• Any errors that occur during the native update steps

Common Android-specific issues you might see in the logs include:

• Network connectivity problems preventing the update download
• File permissions errors when saving or reading the update bundle
• Out of storage space for the update bundle
• Failure to restart the app after the update is installed

iOS Logs

To access the iOS logs:

1. Connect your device or start your simulator
2. Open Xcode and go to “Window > Devices and Simulators”
3. Select your device and click on “Open Console”
4. In the console output, look for any lines that include Capgo to find the SDK logs

You can also use the log stream command in the terminal and grep for Capgo to filter the logs.

Similar to Android, the Capgo SDK will log key iOS-side events:

• Update check initiation and result
• Download start, progress, and completion
• Installation trigger and result
• Any errors during the native update process

iOS-specific issues you might identify in the logs include:

• SSL certificate problems when downloading the update
• App transport security blocking the update download
• Insufficient storage space for the update bundle
• Failure to properly extract or apply the update bundle

On both platforms, the native logs provide a lower-level view into the update process, with more details on the native implementation. They are especially useful for identifying issues that occur outside of the Capgo JavaScript layer.

When troubleshooting a tricky live update problem, it’s a good idea to capture both the Capgo debug logs and the native logs for a comprehensive picture of what’s happening. The two logs together will give you the best chance of identifying and resolving the issue.

Updates not applying

If you’ve uploaded a bundle but aren’t seeing the changes on your device:

• Make sure you’ve called CapacitorUpdater.notifyAppReady() in your app code as shown in the quickstart
• Check that your device is connected to the internet and the Capgo debug logs show the update was downloaded
• Try fully closing and reopening the app, as updates are only applied on a fresh launch
• Look for any errors in the native logs that might indicate a problem applying the update

Refer to the deploying live updates guide for more details on the update process. If you’re still stuck, use the npx @capgo/cli@latest app debug command and native logs to get more visibility into what’s happening.

SDK Installation

If you’re having trouble installing the Capgo SDK, make sure:

• Your app is using a supported version of Capacitor (4.0 or newer)
• You’ve followed the quickstart steps in order, including syncing your app after installing the SDK

CI/CD Integration

For issues with triggering Capgo uploads from your CI/CD pipeline:

• Double check your Capgo authentication token is set up correctly
• Make sure you’re running the upload command after your web assets are built
• Check that the upload command is using the correct channel name for your target environment

See the CI/CD integration docs for more troubleshooting tips. You can also use the npx @capgo/cli@latest app debug command to confirm if your CI/CD-triggered updates are being received by the app.