Troubleshooting Capacitor iOS: Error Umum dan Solusinya

Sebagian besar masalah Capacitor iOS masuk ke lima kelompok: toolchain yang salah, resolusi dependency (SPM atau CocoaPods), error compile dari plugin, signing code, dan masalah runtime seperti “plugin is not implemented” atau WebView kosong. Mulai dari bunx cap doctor, pastikan Xcode 26 sudah terpilih, lalu jalankan bunx cap sync ios, dan baca error pertama di log build Xcode, bukan yang terakhir.

Panduan ini merinci error yang paling sering muncul di proyek Capacitor 8, penyebabnya, dan solusinya. Untuk Android, lihat panduan troubleshooting Capacitor Android.

Checklist pengecekan cepat

Jalankan ini sebelum mencari error spesifik:

bunx cap doctor            # Capacitor, CLI and plugin versions should match
node -v                    # 22 or later for Capacitor 8
xcodebuild -version        # 26.x
xcode-select -p            # should point to the Xcode you expect
bun run build && bunx cap sync ios

• Versi: @capacitor/core, @capacitor/ios dan @capacitor/cli harus memiliki major version yang sama. Ketidakcocokan menyebabkan error compile dan runtime yang aneh. Lihat cara memperbaiki error mismatch versi Capacitor.
• Satu Xcode: jika Anda punya beberapa versi Xcode, xcode-select -p menentukan versi mana yang digunakan CLI. Perbaiki dengan sudo xcode-select -s /Applications/Xcode.app.
• Package manager mana: jika ios/App/CapApp-SPM ada, proyek menggunakan SPM. Jika ios/App/Podfile ada, proyek menggunakan CocoaPods.

Error toolchain

Xcode atau SDK terlalu lama

Gejala: value of type 'WKWebView' has no member 'isInspectable', error sintaks Swift di dalam Capacitor, atau compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 butuh Xcode 26. Di GitHub Actions, macos-latest tidak selalu mengarah ke image dengan Xcode terbaru. Pin image yang menyertakan Xcode 26 dan pilih secara eksplisit:

- run: sudo xcode-select -s /Applications/Xcode_26.0.app

Cek dokumentasi runner image untuk path pastinya. Untuk error module-minimum, naikkan deployment target app Anda ke minimum plugin, atau gunakan versi plugin yang lebih lama.

ITMS-90725: SDK version issue saat upload

Build dibuat dengan SDK yang lebih lama dari standar Apple saat ini. Sejak 28 April 2026, upload harus menggunakan Xcode 26 dan iOS 26 SDK. Lihat Syarat Xcode 26 Apple untuk aplikasi Capacitor. Build Capgo sudah bisa di-build di Xcode 26 jika Anda tidak ingin mengelola Mac runners.

Error Swift Package Manager

Missing package product 'CapApp-SPM'

Xcode gagal resolve package lokal, atau cache sudah usang.

1. File > Packages > Reset Package Caches.
2. File > Packages > Resolve Package Versions.
3. Jika aplikasi dimigrasi dari CocoaPods, pastikan CapApp-SPM sudah ditambahkan di bawah Package Dependencies proyek tab dan ditautkan ke target App.

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

Sebuah plugin Package.swift menggunakan nama package atau produk yang tidak sesuai dengan CLI Capacitor yang dihasilkan dari nama npm. Ini adalah bug plugin. Update plugin tersebut, atau patch it. Pembuat plugin dapat menemukan aturan penamaan di migrasi plugin Capacitor ke SPM.

“Beberapa Capacitor plugin yang terinstal tidak kompatibel dengan SPM”

Peringatan ini saat cap sync berarti setidaknya satu plugin tidak memiliki Package.swift. Plugin tersebut tidak disertakan dalam app, sehingga pemanggilan akan gagal dengan pesan “not implemented”. Upgrade plugin, ganti dengan yang mendukung SPM, atau gunakan CocoaPods untuk saat ini.

Duplikasi identitas package atau nama target

Dua plugin memiliki identitas package atau nama target yang sama (seringkali nama generik seperti Plugin). Sejak CLI 8.4, Anda bisa memperbaikinya melalui konfigurasi Capacitor:

const config: CapacitorConfig = {
  // ...
  experimental: {
    ios: {
      spm: {
        packageOptions: {
          '@acme/capacitor-foo': { symlink: true },
          '@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
        },
      },
    },
  },
};

symlink membuat referensi CLI ke plugin melalui folder symlink dengan path unik. moduleAliases mengubah nama modul yang konflik untuk dependency tersebut. Laporkan juga konflik ini ke upstream.

Jangan edit CapApp-SPM/Package.swift

CLI akan menulis ulang file tersebut setiap kali sync. Editan lokal akan hilang. Gunakan experimental.ios.spm opsi konfigurasi sebagai gantinya.

Error CocoaPods

No such module 'Capacitor'

Anda membuka App.xcodeproj bukannya App.xcworkspace. Gunakan bunx cap open ios. Jika workspace terbuka dan error masih ada, jalankan bunx cap sync ios untuk menginstal ulang pods.

CocoaPods could not find compatible versions for pod "X"

Dua penyebabnya:

1. Repo spec usang: jalankan cd ios/App && pod install --repo-update.
2. Conflicting pins: dua plugin membutuhkan versi yang tidak kompatibel dari pod yang sama. Error akan menampilkan rantainya. Upgrade plugin yang memakai pin ketat, samakan versinya (untuk Firebase, pertahankan semua plugin Firebase di versi SDK yang sama), atau patch podspec-nya.

Jika masih gagal, hapus ios/App/Podfile.lock dan ios/App/Pods, lalu sync lagi. Ini juga meng-upgrade semua pod, jadi tes setelahnya.

The sandbox is not in sync with the Podfile.lock

Jalankan bunx cap sync ios. Ini terjadi setelah pindah branch atau instalasi parsial.

Unable to find compatibility version string for object version '70'

Milik Anda project.pbxproj menggunakan format yang tidak bisa dibaca versi CocoaPods Anda. Update CocoaPods (brew upgrade cocoapods atau naikkan versinya di Gemfile). Sebagai langkah terakhir, backup file tersebut dan turunkan objectVersion.

Sandbox: rsync(...) deny(1) file-write-create

sandboxing user script Xcode memblokir script embed framework CocoaPods. Atur Build Settings > User Script Sandboxing ke Tidak pada target App.

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

Build simulator berjalan untuk Intel. Pada Apple Silicon, ini biasanya berarti Xcode berjalan di bawah Rosetta atau EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 pengaturan lama masih tersisa dari workaround sebelumnya. Jalankan Xcode secara native, hapus pengaturan tersebut dari target App dan post_install hook, lalu clean dan rebuild.

Error kompilasi

Command PhaseScriptExecution failed with a nonzero exit code

Ini hanyalah wrapper. Buka build phase yang error di Report navigator dan baca output script-nya. Penyebab umum pada aplikasi Capacitor:

• Run Script membutuhkan node dan Xcode tidak bisa menemukannya, karena Xcode tidak memuat shell profile Anda dan Node terinstal via nvm, fnm, atau Volta. Gunakan full path ke node di dalam script, atau export PATH di bagian atasnya.
• Script upload crash reporting (Sentry, Crashlytics) kehilangan kredensial di CI.
• Script embed CocoaPods terblokir oleh user script sandboxing (lihat di atas).

'X' is only available in iOS 16.0 or newer

Plugin menggunakan API di atas deployment target Anda. Naikkan target di Xcode, di Podfile ("platform :ios, '16.0'") jika menggunakan CocoaPods, dan cek README plugin untuk versi minimumnya.

Error concurrency Swift 6 pada plugin

Pesan seperti Sending 'x' risks causing data races muncul saat plugin atau target app Anda menggunakan Swift 6 language mode. Capacitor 8 belum mendukung Swift 6 secara resmi. Tetap gunakan Swift 5 language mode pada target App sampai plugin diperbarui.

penandatanganan Code

Signing for "App" requires a development team

Buka Target App > Signing & Capabilities dan pilih team. Di CI, masukkan DEVELOPMENT_TEAM ke xcodebuild atau gunakan signing tool. Jika error menyebutkan pod resource bundle alih-alih App, nonaktifkan signing untuk bundle targets di Podfile post_install hook.

Provisioning profile "X" doesn't include the ... entitlement

You added a capability (Push Notifications, Associated Domains, Sign in with Apple) without regenerating the profile. Enable it on the App ID in the Apple Developer portal, then refresh profiles. Our generator sertifikat iOS membantu membuat sertifikat tanpa ribet dengan Mac keychain, dan Pencari UDID membantu mendaftarkan perangkat testing.

Unable to install "App" di perangkat

Aktifkan Developer Mode di perangkat (Settings > Privacy & Security > Developer Mode), percayai sertifikat developer, dan pastikan UDID perangkat sudah terdaftar dalam provisioning profile untuk development build.

Runtime error

"X" plugin is not implemented on ios

Sisi JavaScript tidak menemukan implementasi native. Cek dengan urutan berikut:

1. Plugin sudah ada di package.json and you ran bunx cap sync ios setelah menginstalnya.
2. Untuk SPM: plugin muncul di ios/App/CapApp-SPM/Package.swift. Jika tidak, plugin tidak memiliki Package.swift.
3. Untuk CocoaPods: plugin muncul di capacitor_pods block Podfile dan pod install tidak menampilkan peringatan apa pun.
4. Tidak ada dua plugin yang mendaftarkan nama JS yang sama (misalnya dua plugin push notification).
5. WKAppBoundDomains tidak ada di Info.plist, atau jika ada, limitsNavigationsToAppBoundDomains sudah diatur dan localhost sudah terdaftar. Jika tidak, app-bound domains akan memblokir injeksi script plugin.
6. Bersihkan folder build lalu build ulang. Build lama sering menyimpan registrasi plugin yang usang.

Layar putih kosong saat startup

Periksa WebView menggunakan Safari Web Inspector terlebih dahulu. Sebagian besar layar kosong disebabkan oleh error JavaScript.

• Salah webDir: capacitor.config.ts mengarahkan ke folder yang tidak berisi index.html. Periksa ios/App/App/public.
• Target build terlalu baru: bundler Anda menghasilkan sintaks lama yang tidak didukung WebKit. iOS 15 adalah minimum untuk Capacitor 8, jadi targetkan safari15 atau versi lebih baru di Vite/esbuild dan periksa browserslist.
• Path aset absolut: base pengaturan ke CDN atau subpath di config bundler merusak pemuatan lokal.
• Live reload tidak dapat dijangkau: dev server harus mendengarkan di IP LAN Anda (--host 0.0.0.0), ponsel harus berada di jaringan yang sama, dan aplikasi butuh izin Local Network (Settings > Privacy & Security > Local Network). Hapus server.url dari config sebelum melakukan release build.
• bundle Live update rusak: jika aplikasi menggunakan OTA updates, bundle yang rusak bisa membuat layar kosong. Updater Capgo akan melakukan rollback otomatis saat notifyAppReady() tidak dipanggil tepat waktu. Lihat dokumentasi updater.

Konten berada di bawah notch atau home indicator

Tambah viewport-fit=cover ke viewport meta tag Anda dan beri padding dengan env(safe-area-inset-top) dan env(safe-area-inset-bottom). Plugin System Bars dari Capacitor 8 mengontrol gaya dan visibilitas status bar di kedua platform.

Keyboard menutupi input

Konfigurasi plugin Keyboard resize mode (native, body, ionic atau none) dan tes di perangkat asli. Simulator menangani keyboard secara berbeda.

Error App Store Connect

• ITMS-91053: Missing API declaration: aplikasi atau plugin Anda menggunakan API yang diwajibkan tanpa entri privacy manifest. Tambahkan PrivacyInfo.xcprivacy ke target App beserta alasannya, dan perbarui plugin yang menyertakan manifest sendiri.
• ITMS-90725: SDK version issue: build ulang dengan Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': sebuah framework tertanam di dalam extension atau framework lain. Periksa Embed settings untuk app extensions.

Cara debug jika error tidak terdaftar

1. Safari Web Inspector untuk error JS dan network calls. Debug build bisa di-inspect di iOS 16.4+. Untuk release build, atur ios.webContentsDebuggingEnabled: true sementara.
2. Konsol Xcode untuk log native, termasuk Capacitor ⚡️ pesan bridge yang menampilkan setiap pemanggilan plugin.
3. Console.app dengan perangkat terpilih untuk log crash dan sistem.
4. Isolasi: buat app baru dengan bun create @capacitor/app, tambahkan hanya plugin yang dicurigai, dan cek apakah error muncul kembali.

Skill panduan lengkap debugging app Capacitor membahas lebih dalam tiap tool. Jika penyebab utamanya adalah bug plugin, maka patch biasanya cara tercepat untuk unblock sementara menunggu rilis baru.