The iOS Troubleshooting Guide for Capacitor¶

Capacitor is a great tool to build cross-platform apps with web technologies. However, sometimes you might run into issues when building your iOS app. This post will help you to troubleshoot common issues.

Help us to improve this guide

If you are aware of any other common issues, please send us an email to [email protected] so that we can update the guide.

Errors¶

`could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'`¶

This error indicates that the Capacitor module is not available for the x86_64 architecture which is used by the iOS simulator.

Add the following post_install hook to your Podfile (usually ios/App/Podfile):

post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |config|
            # Build for all architectures
            config.build_settings['ONLY_ACTIVE_ARCH'] = 'NO'
            # Exclude arm64 architecture for the iOS simulator
            config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
        end
    end
end

The ONLY_ACTIVE_ARCH build setting is set to YES by default, which means that the build system will only build for the active architecture. By setting it to NO, the build system will build for both arm64 and x86_64 architectures, making the Capacitor module available for the iOS simulator.

The EXCLUDED_ARCHS[sdk=iphonesimulator*] build setting is used to exclude the arm64 architecture for the iOS simulator.

`value of type 'WKWebView' has no member 'isInspectable'`¶

This error occurs if you are using an outdated version of XCode. For Capacitor 6 you need at least Xcode 15.0, so make sure you are using the latest version of Xcode.

If this error occurs in GitHub Actions, you should update the macOS version to macos-14 in your workflow file. Please note that macos-latest is not always the latest version (see here).

- runs-on: macos-latest
+ runs-on: macos-14

`CocoaPods could not find compatible versions for pod "..."`¶

This error occurs when CocoaPods cannot find compatible versions for a pod. This can either be due to outdated sources or other dependencies that require different versions of the same pod.

Follow the steps below to find out if outdated sources are causing the problem:

Delete the Podfile.lock (usually ios/App/Podfile.lock) file and the Pods directory (usually ios/App/Pods).
Run pod install --repo-update where the Podfile is located (usually ios/App).

If the problem persists, you need to check the dependencies in your Podfile and make sure that all dependencies use the same version of the pod. For example, this was one of the reasons why we created the Capacitor Firebase Plugin Collection to ensure that all Firebase plugins use the same version of the Firebase SDK.

Plugin is not implemented¶

If Capacitor cannot find a plugin or cannot inject its code into the WebView, the following error is thrown, for example:

"Badge" plugin is not implemented

Follow the steps below to solve this issue:

Make sure that the plugin is installed and appears in the package.json.
Sync the native project by running npx cap sync ios.
Make sure that the plugin is listed in ios/App/Podfile.
Make sure that no other plugin is installed that might conflict with the plugin. For example, do not install two different Push Notification plugins.
Make sure that you do not have WKAppBoundDomains key in your Info.plist file. This key is used to restrict the domains that your app can access and can cause issues with plugins that need to inject code into the WebView.

Blank screen¶

A blank screen can have many causes. Here are some common reasons and solutions.

With live reload¶

If you see a blank screen when using live reload, check the following:

Make sure that your development server uses all network interfaces and not only localhost. For example, if you are using the Ionic CLI, you can use the --external option to bind to all network interfaces:
```
ionic cap run ios -l --external
```
Make sure that your development server is accessible from the device. You can check this by opening the URL in the device's browser. If the URL is not accessible, the app will not be able to load the content. This may be due to the following reasons:
- The device is not connected to the same network as the development server.
- The development server is not accessible from the device due to firewall settings.
Make sure that the content is not blocked by a Content Security Policy (CSP) or other security mechanisms. You can check this by opening the browser's developer tools and looking for errors in the console.

Without live reload¶

If you see a blank screen without live reload, check the following:

If you are using Angular, make sure that your .browserslistrc or browserslist file includes the browser versions you need to support. The Angular CLI uses this file to determine which code it can optimize. Check out this topic for more information.