--- description: Troubleshoot common issues when building your iOS app with Capacitor, including errors related to modules, plugins, and blank screens. title: The iOS Troubleshooting Guide for Capacitor - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/troubleshooting-capacitor-ios-issues.png --- [Skip to content ](#the-ios-troubleshooting-guide-for-capacitor) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ Version 70 error ](#version-70-error) * [ FAQ ](#faq) * [ Related Posts ](#related-posts) # The iOS Troubleshooting Guide for Capacitor[ΒΆ](#the-ios-troubleshooting-guide-for-capacitor "Permanent link") 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 [support@capawesome.io](mailto:support@capawesome.io) so that we can update the guide. ## Errors[ΒΆ](#errors "Permanent link") ### `could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'`[ΒΆ](#could-not-find-module-capacitor-for-target-x86%5F64-apple-ios-simulator "Permanent link") 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`): `[](#%5F%5Fcodelineno-0-1)post_install do |installer| [](#%5F%5Fcodelineno-0-2) installer.pods_project.targets.each do |target| [](#%5F%5Fcodelineno-0-3) target.build_configurations.each do |config| [](#%5F%5Fcodelineno-0-4) # Build for all architectures [](#%5F%5Fcodelineno-0-5) config.build_settings['ONLY_ACTIVE_ARCH'] = 'NO' [](#%5F%5Fcodelineno-0-6) # Exclude arm64 architecture for the iOS simulator [](#%5F%5Fcodelineno-0-7) config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64' [](#%5F%5Fcodelineno-0-8) end [](#%5F%5Fcodelineno-0-9) end [](#%5F%5Fcodelineno-0-10)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'`[ΒΆ](#value-of-type-wkwebview-has-no-member-isinspectable "Permanent link") This error occurs if you are using an outdated version of Xcode β€” `isInspectable` requires Xcode 15 or later. Apple's toolchain requirement moves forward regularly; see [Apple's New Xcode 26 Requirement for Capacitor Apps](/blog/xcode-26-requirement-for-capacitor-apps/) for the current minimum required to submit to the App Store. If this error occurs in GitHub Actions, your runner image is pinned to an old Xcode version. Please note that `macos-latest` does not always map to the newest available Xcode (see [here](https://twitter.com/jcesarmobile/status/1780142061129204204)) β€” check [GitHub's runner image matrix](https://github.com/actions/runner-images) for the macOS image that ships the Xcode version your app needs, and pin to it explicitly: `[](#%5F%5Fcodelineno-1-1)- runs-on: macos-latest [](#%5F%5Fcodelineno-1-2)+ runs-on: macos-15 ` ### `CocoaPods could not find compatible versions for pod "..."`[ΒΆ](#cocoapods-could-not-find-compatible-versions-for-pod "Permanent link") 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](/docs/sdks/capacitor/firebase/) Plugin Collection to ensure that all Firebase plugins use the same version of the Firebase SDK. ### Plugin is not implemented[ΒΆ](#plugin-is-not-implemented "Permanent link") If Capacitor cannot find a plugin or cannot inject its code into the WebView, the following error is thrown, for example: `[](#%5F%5Fcodelineno-2-1)"Badge" plugin is not implemented ` Follow the steps below to solve this issue: 1. Make sure that the plugin is installed and appears in the `package.json`. 2. Sync the native project by running `npx cap sync ios`. 3. Make sure that no other plugin is installed that might conflict with the plugin. For example, do not install two different Push Notification plugins. 4. 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. 5. If you are using CocoaPods instead of Swift Package Manager, make sure that the plugin is listed in `ios/App/Podfile`. 6. If you are using CocoaPods instead of Swift Package Manager, make sure that CocoaPods was installed correctly and no warning is shown when running `npx cap sync ios`. 7. Make sure to use the latest Node.js and npm version. Run `node -v` and `npm -v` to check your versions. 8. Make sure to use the latest Capacitor CLI version. Run `npx cap doctor` to check your versions. 9. Make sure you only have one version of Xcode installed. You can check this by running `xcode-select -p` in the terminal. If the problem persists, check the following GitHub issues and discussions for more information: * https://github.com/capacitor-community/sqlite/issues/662#issuecomment-3364677943 * https://github.com/capawesome-team/capacitor-plugins/discussions/617#discussioncomment-14527491 ### Blank screen[ΒΆ](#blank-screen "Permanent link") A blank screen can have many causes. Here are some common reasons and solutions. #### With live reload[ΒΆ](#with-live-reload "Permanent link") If you see a blank screen when using live reload, check the following: 1. 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: `[](#%5F%5Fcodelineno-3-1)ionic cap run ios -l --external ` 2. 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. 3. 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[ΒΆ](#without-live-reload "Permanent link") If you see a blank screen without live reload, check the following: 1. 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](https://forum.ionicframework.com/t/ionic-6-default-project-white-screen-on-android-30-or-below-when-using-prod/228087) for more information. ### Version 70 error[ΒΆ](#version-70-error "Permanent link") You may encounter the following error when building your iOS app: `` [](#%5F%5Fcodelineno-4-1)Unable to find compatibility version string for object version `70`. `` This is caused by Xcode when you add an extension file to your project. The problem is in your Xcode project `pbxproj` file. Open this file and change objectVersion from 70 to 60. ## FAQ[ΒΆ](#faq "Permanent link") ### How do I clean and rebuild my iOS project?[ΒΆ](#how-do-i-clean-and-rebuild-my-ios-project "Permanent link") A clean rebuild clears many iOS build errors. Delete `ios/App/Pods` and `ios/App/Podfile.lock`, clear Xcode's DerivedData (**Xcode > Settings > Locations**), then run `npx cap sync ios` and, if you use CocoaPods, `pod install --repo-update` in `ios/App`. Reopen the project with `npx cap open ios` and build again. ### Should I use CocoaPods or Swift Package Manager?[ΒΆ](#should-i-use-cocoapods-or-swift-package-manager "Permanent link") Capacitor supports both, and Swift Package Manager (SPM) is the modern default for new apps. If you keep hitting CocoaPods dependency conflicts like the one above, migrating can simplify things β€” see [how to migrate a Capacitor app to SPM](/blog/how-to-migrate-a-capacitor-app-to-spm/). ### Why don't my web code changes show up in the app?[ΒΆ](#why-dont-my-web-code-changes-show-up-in-the-app "Permanent link") Capacitor bundles your **built** web assets into the native app, so editing source files isn't enough. Rebuild the web app and copy it over with `npx cap sync ios` (or `npx cap copy ios`), then run the app again. During active development, use live reload so changes appear instantly. ### How do I inspect the WebView and see console logs?[ΒΆ](#how-do-i-inspect-the-webview-and-see-console-logs "Permanent link") On a Mac, open **Safari > Develop > \[your device\] > \[your app\]** to attach Safari Web Inspector to the WebView, where you can read console logs and inspect the DOM. The WebView is inspectable by default in development builds on iOS 16.4 and later. ### Which Xcode version do I need for Capacitor?[ΒΆ](#which-xcode-version-do-i-need-for-capacitor "Permanent link") Use the latest stable Xcode. Capacitor 6 requires Xcode 15 or later, and newer Capacitor majors track the current Xcode release. In CI, pin a specific macOS image (for example `macos-14`) rather than `macos-latest`, which isn't always the newest. ### My app still won't build after fixing an error β€” what next?[ΒΆ](#my-app-still-wont-build-after-fixing-an-error-what-next "Permanent link") Run `npx cap doctor` to check your Capacitor, Node, and plugin versions, confirm you have a single Xcode installed with `xcode-select -p`, and if the issue is plugin-specific, try [patching the plugin](/blog/how-to-patch-a-capacitor-plugin/). For Android-side issues, see [The Android Troubleshooting Guide for Capacitor](/blog/troubleshooting-capacitor-android-issues/). ## Related Posts[ΒΆ](#related-posts "Permanent link") * [How to Fix Capacitor Plugin Build Errors with AGP 9](/blog/how-to-fix-capacitor-plugin-build-errors-with-agp-9/) * [How to patch a Capacitor plugin](/blog/how-to-patch-a-capacitor-plugin/) * [The Android Troubleshooting Guide for Capacitor](/blog/troubleshooting-capacitor-android-issues/) July 16, 2026 Back to top ```json { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "The iOS Troubleshooting Guide for Capacitor", "description": "Troubleshoot common issues when building your iOS app with Capacitor, including errors related to modules, plugins, and blank screens.", "image": "https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png", "datePublished": "2024-03-12T00:00:00+00:00", "dateModified": "2026-07-14T00:00:00+00:00", "author": [ { "@type": "Person", "name": "Robin Genz", "url": "https://github.com/robingenz" } ], "publisher": { "@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": { "@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg" } }, "articleSection": "Capacitor", "keywords": ["Capacitor", "Guides"], "isPartOf": { "@type": "Blog", "@id": "https://capawesome.io/blog/#blog" }, "mainEntityOfPage": "https://capawesome.io/blog/troubleshooting-capacitor-ios-issues/", "url": "https://capawesome.io/blog/troubleshooting-capacitor-ios-issues/" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://capawesome.io/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://capawesome.io/blog/" }, { "@type": "ListItem", "position": 3, "name": "The iOS Troubleshooting Guide for Capacitor", "item": "https://capawesome.io/blog/troubleshooting-capacitor-ios-issues/" } ] } {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How do I clean and rebuild my iOS project?", "acceptedAnswer": {"@type": "Answer", "text": "A clean rebuild clears many iOS build errors. Delete ios/App/Pods and ios/App/Podfile.lock, clear Xcode's DerivedData ( Xcode > Settings > Locations), then run npx cap sync ios and, if you use CocoaPods, pod install --repo-update in ios/App. Reopen the project with npx cap open ios and build again."}}, {"@type": "Question", "name": "Should I use CocoaPods or Swift Package Manager?", "acceptedAnswer": {"@type": "Answer", "text": "Capacitor supports both, and Swift Package Manager (SPM) is the modern default for new apps. If you keep hitting CocoaPods dependency conflicts like the one above, migrating can simplify things β€” see how to migrate a Capacitor app to SPM."}}, {"@type": "Question", "name": "Why don't my web code changes show up in the app?", "acceptedAnswer": {"@type": "Answer", "text": "Capacitor bundles your built web assets into the native app, so editing source files isn't enough. Rebuild the web app and copy it over with npx cap sync ios (or npx cap copy ios), then run the app again. During active development, use live reload so changes appear instantly."}}, {"@type": "Question", "name": "How do I inspect the WebView and see console logs?", "acceptedAnswer": {"@type": "Answer", "text": "On a Mac, open Safari > Develop > [your device] > [your app] to attach Safari Web Inspector to the WebView, where you can read console logs and inspect the DOM. The WebView is inspectable by default in development builds on iOS 16.4 and later."}}, {"@type": "Question", "name": "Which Xcode version do I need for Capacitor?", "acceptedAnswer": {"@type": "Answer", "text": "Use the latest stable Xcode. Capacitor 6 requires Xcode 15 or later, and newer Capacitor majors track the current Xcode release. In CI, pin a specific macOS image (for example macos-14) rather than macos-latest, which isn't always the newest."}}, {"@type": "Question", "name": "My app still won't build after fixing an error β€” what next?", "acceptedAnswer": {"@type": "Answer", "text": "Run npx cap doctor to check your Capacitor, Node, and plugin versions, confirm you have a single Xcode installed with xcode-select -p, and if the issue is plugin-specific, try patching the plugin. For Android-side issues, see The Android Troubleshooting Guide for Capacitor."}}], "url": "https://capawesome.io/blog/troubleshooting-capacitor-ios-issues/"} ```