Skip to content

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:

  1. Delete the Podfile.lock (usually ios/App/Podfile.lock) file and the Pods directory (usually ios/App/Pods).
  2. 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.