Skip to main content
Version: v2

iOS Troubleshooting Guide

Creating a 100% perfect native management tool is nearly impossible, and sooner or later you'll run into various issues with some part of the iOS workflow.

This guide attempts to document common iOS/Xcode issues with possible solutions.

iOS Toolbox​

Every iOS developer learns a few common techniques for debugging iOS issues, and you should incorporate these into your workflow:

Google, Google, Google​

Any time you encounter an issue with iOS, or Xcode, your first step should be to copy and paste the error into a Google search.

Capacitor uses the standard iOS toolchain, so chances are if you run into something, many iOS developers have as well, and there's a solution out there.

It could be as simple as updating a dependency, running clean, or removing Derived Data.

Clean/Rebuild​

Cleaning and rebuilding can fix a number of build issues. Navigate to Product -> Clean Build Folder in the Xcode menu to clean your current build.

Removing Derived Data​

Sometimes, Xcode clings to old, outdated build artifacts. To start fresh, you'll need to delete any Derived Data on disk.

To do this, open Xcode Preferences, choose the Locations tab, and click the small arrow next to your Derived Data path:

Locations

This opens a Finder window to the location of Xcode's temporary Derived Data.

Next, select all items in that directory and delete:

Deleting Derived Data

Finally, do a rebuild in Xcode.

Error: Unable to export required Bridge JavaScript​

Can't export

This error occurs when Capacitor's native-bridge.js file was not copied to the native project.

The fix is simple: run npx cap copy ios to copy this file.

Error: Sandbox not in sync with the Podfile.lock​

This error can happen if CocoaPods hasn't been able to run to install your dependencies.

Run this to update your pods:

npx cap update ios

Perform a new build after running this command.

Indexing FOREVER​

Xcode sometimes gets stuck indexing forever. This unfortunate situation looks like this:

Xcode indexing

The only solution is to Force Close Xcode (using Activity Monitor) and start it up again.

CocoaPods: Failed to connect to GitHub​

This error can happen on Macs with an old version of openssl and ruby installed, since GitHub restricted the allowed cryptographic protocols when accessing repos.

The solution is to update openssl and update Ruby:

brew install openssl
brew upgrade openssl
brew install ruby
brew link --overwrite ruby

Finally, make sure your PATH environment variable does not put /usr/local/bin after $PATH, but rather before it.

See this StackOverflow issue for other possible solutions to this problem.

Contents

Edit this page