Capacitor Plugin Native Build Failures in Ionic: Diagnostic Guide

Recognizable Condition

npx cap sync completes successfully, but the native build fails in Xcode or Android Studio with errors such as Plugin not found, Module not found, or Duplicate class. The JavaScript package installed without issue, yet the native iOS or Android project never registered the plugin.

Capacitor is the native bridge that lets Ionic web code call device APIs through plugins. A plugin has a JavaScript package and a native implementation—Swift or Objective-C for iOS, Kotlin or Java for Android. cap sync copies web assets and updates native configuration, but it does not compile native code, so a clean sync does not guarantee a clean build.

Cause and Diagnostic Table

Error pattern	Most likely cause	Where to check
Plugin class not found in native code	Native dependency not installed or linked	ios/App/Podfile and android/build.gradle.kts
Duplicate class or method	Multiple plugins pull different versions of the same library	Run ./gradlew app:dependencies in the Android folder
Swift module not found	Missing use_frameworks! in the iOS Podfile	Inspect ios/App/Podfile for Swift plugins
AndroidX or legacy support error	Plugin references deprecated android.support packages	Search plugin source for import android.support

Ordered Diagnostic Checks

1. Run Capacitor Doctor
   Run npx cap doctor from the project root. It reports CLI, Xcode, Android Studio, CocoaPods, and Gradle versions. Note any version mismatch warnings.
2. Verify plugin versions
   Open package.json. @capacitor/core, @capacitor/cli, @capacitor/ios, and @capacitor/android must share the same major version. Each plugin should match that major version in its peerDependencies.
3. Inspect the iOS Podfile
   Open ios/App/Podfile. If any installed plugin uses Swift, confirm use_frameworks! :linkage => :static appears before the target blocks.
4. Check Android Gradle configuration
   Open android/build.gradle.kts. Confirm compileSdk and targetSdk satisfy the plugin requirements, and look for mixed androidx and legacy com.android.support references.
5. Clean and resync
   Delete ios/Pods, android/.gradle, and android/app/build, then run npx cap sync again from the project root.
6. Inspect resolved dependencies
   On iOS, review ios/Podfile.lock. On Android, run cd android && ./gradlew app:dependencies --configuration debugRuntimeClasspath to locate version conflicts.

Fixes Tied to Findings

• Missing native install
  Run npx cap sync, then cd ios && pod install --repo-update for iOS. For Android, run cd android && ./gradlew clean before rebuilding. These commands assume Xcode or Android Studio is installed and that you have normal user permissions; pod install requires network access to CocoaPods repositories.
• Version mismatch
  Align the plugin with your Capacitor major version. Example, replacing <plugin> with the plugin name:
  

  npm install @capacitor/core@6 @capacitor/<plugin>@6

  Check the plugin's peerDependencies before installing.
• Duplicate Android dependencies
  Add a resolution strategy in android/build.gradle.kts to force one version. The version below is illustrative; substitute the version identified by the dependency check:
  

  allprojects {
      configurations.all {
          resolutionStrategy {
              force("com.google.firebase:firebase-bom:32.7.0")
          }
      }
  }

  Editing build files is safe here because these are project files, not generated folders.
• iOS bridging issues
  Ensure ios/App/Podfile contains:
  

  platform :ios, '13.0'
  use_frameworks! :linkage => :static

  Then run cd ios && pod install.
• AndroidX migration
  If a plugin still uses android.support, it has not been migrated to AndroidX. Contact the maintainer or fork the plugin and replace those imports with androidx equivalents. npx cap migrate can help with Capacitor-managed code, but it does not rewrite third-party plugin source.

Escalation Criteria

Escalate to the plugin maintainer or the Capacitor plugins repository when:

• The plugin has no release in 12 or more months and fails on the latest Capacitor, iOS SDK, or Android API level.
• npx cap doctor reports no issues, but the native build fails with plugin-specific symbol errors.
• Two first-party Capacitor plugins conflict, such as registering the same native service.
• You are blocked in production with no workaround after four hours of diagnosis.

Limitations and Verification

Important limitations:

• Capacitor 6 and later assume Xcode 15 or later and iOS 13 as the minimum deployment target. Older plugins may lack the privacy manifest entries required for App Store submission.
• Android 14 (API 34) enforces stricter foreground service types. Plugins using background location, Bluetooth, or media playback must declare the appropriate android:foregroundServiceType attributes in the manifest.
• Never manually edit files in ios/App/Pods or android/app/build/generated. These directories are regenerated during cap sync, so changes are lost.
• Avoid npm audit fix --force. It can upgrade Capacitor core without updating plugins, creating silent version skew.
• Live Reload (ionic cap run -l --external) bypasses native plugin code. Test plugins on a physical device without the -l flag to verify permissions, background modes, and hardware integration.

Verification Steps

1. Run npx cap doctor and confirm there are no warnings about CLI, Xcode, Android Studio, CocoaPods, or Gradle versions.
2. Verify in package.json that @capacitor/core, @capacitor/cli, @capacitor/ios, and @capacitor/android all use the same major version.
3. Check ios/Podfile.lock and android/app/build.gradle.kts for resolved dependency versions that align with your plugin requirements.
4. Perform a clean build. From the project root: npx cap sync && cd ios && xcodebuild -workspace App.xcworkspace -scheme App -configuration Debug -destination 'generic/platform=iOS'. For Android: cd android && ./gradlew assembleDebug. Replace App with your actual workspace and scheme names.
5. Test plugin functionality on a physical device rather than a simulator to confirm permissions, background modes, and hardware features work as expected.