Troubleshooting Capacitor iOS: Error Umum dan Solusinya

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

Panduan ini merangkum error yang paling sering kami temui di proyek Capacitor 8, penyebab masing-masing, dan solusinya. Untuk Android, lihat panduan troubleshooting Capacitor Android.

Checklist triage cepat

Jalankan langkah-langkah ini sebelum mengejar 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 versi major 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 mana yang dipakai 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 membutuhkan 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 yang diterima Apple saat ini. Sejak 28 April 2026, upload harus di-build dengan Xcode 26 dan iOS 26 SDK. Lihat Persyaratan Xcode 26 dari Apple untuk app Capacitor. Build Capgo sudah build di Xcode 26 jika Anda tidak mau mengurus Mac runner.

Error Swift Package Manager

Missing package product 'CapApp-SPM'

Xcode belum me-resolve package lokal, atau cache-nya 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 Dependensi Package tab dan ditautkan ke target App.

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

Plugin Package.swift menggunakan nama package atau produk yang tidak cocok dengan yang dihasilkan Capacitor CLI dari nama npm-nya. Ini bug plugin. Update pluginnya, atau patch saja. Pembuat plugin dapat menemukan aturan penamaan di migrasi plugin Capacitor ke SPM.

“Beberapa plugin Capacitor yang terinstal tidak kompatibel dengan SPM”

Peringatan ini saat cap sync berarti setidaknya satu plugin tidak memiliki Package.swift. Plugin itu tidak disertakan ke app, jadi panggilan ke plugin tersebut gagal dengan “not implemented”. Upgrade pluginnya, ganti dengan plugin yang mendukung SPM, atau pakai CocoaPods dulu.

Identitas package atau nama target duplikat

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

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

symlink membuat CLI merujuk ke plugin melalui folder symlink dengan path yang unik. moduleAliases mengganti nama modul yang konflik untuk dependency tersebut. Laporkan juga konfliknya ke upstream.

Jangan edit CapApp-SPM/Package.swift

CLI menulis ulang file itu di setiap sync. Perubahan lokal akan hilang. Gunakan experimental.ios.spm opsi konfigurasi sebagai gantinya.

Error CocoaPods

No such module 'Capacitor'

Anda membuka App.xcodeproj alih-alih App.xcworkspace. Gunakan bunx cap open ios. Jika workspace sedang terbuka dan error tetap muncul, 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. Pin yang bentrok: dua plugin membutuhkan versi yang tidak kompatibel dari pod yang sama. Error akan menampilkan rantai konfliknya. Upgrade plugin yang memakai pin ketat, samakan versi (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 setiap pod, jadi uji 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'

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

User script sandboxing di 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. Di Apple Silicon, ini biasanya berarti Xcode berjalan di bawah Rosetta atau ada EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 pengaturan tersebut adalah sisa dari solusi sementara sebelumnya. Jalankan Xcode secara native, hapus pengaturan tersebut dari target App dan semua post_install hook, lalu clean dan rebuild.

Error kompilasi

Command PhaseScriptExecution failed with a nonzero exit code

Ini hanya wrapper. Buka build phase yang gagal di Report navigator dan baca output script-nya. Penyebab umum di 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) tidak punya 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 memakai API di atas deployment target Anda. Naikkan target di Xcode, di Podfile (platform :ios, '16.0') jika memakai CocoaPods, dan cek README plugin untuk versi minimumnya.

Error concurrency Swift 6 di plugin

Pesan seperti Sending 'x' risks causing data races muncul saat plugin atau target app Anda memakai Swift 6 language mode. Capacitor 8 belum mendukung Swift 6 secara resmi. Biarkan target App tetap di Swift 5 language mode sampai plugin diperbarui.

signing Code

Signing for "App" requires a development team

Buka Target App > Signing & Capabilities dan pilih team. Di CI, teruskan DEVELOPMENT_TEAM ke xcodebuild atau gunakan signing tool. Jika error menyebut pod resource bundle, bukan App, matikan signing untuk target bundle di Podfile post_install hook.

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

Anda menambahkan capability (Push Notifications, Associated Domains, Sign in with Apple) tanpa regenerate profile. Aktifkan di App ID pada portal Apple Developer, lalu refresh profile. iOS certificate generator kami membantu membuat sertifikat tanpa ribet urusan 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), percaya pada sertifikat developer, dan pastikan UDID perangkat ada di provisioning profile untuk build development.

Error runtime

"X" plugin is not implemented on ios

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

1. Plugin 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, berarti tidak ada Package.swift.
3. Untuk CocoaPods: plugin muncul di capacitor_pods blok di Podfile dan pod install tidak menampilkan peringatan.
4. Anda tidak punya dua plugin yang mendaftarkan nama JS yang sama (misalnya dua plugin push notification).
5. WKAppBoundDomains tidak ada di Info.plist, atau jika ada, limitsNavigationsToAppBoundDomains diatur dan localhost terdaftar. Jika tidak, app-bound domains akan memblokir injeksi script plugin.
6. Bersihkan folder build dan build ulang. Build lama masih menyimpan registrasi plugin lama.

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 mengarah ke folder yang tidak berisi index.html. Periksa ios/App/App/public.
• Target build terlalu baru: bundler Anda menghasilkan sintaks yang tidak didukung WebKit lama. iOS 15 adalah minimum untuk Capacitor 8, jadi targetkan safari15 atau lebih baru di Vite/esbuild dan periksa browserslist.
• Path aset absolut: base base yang di-set ke CDN atau subpath di config bundler merusak loading lokal.
• Live reload tidak dapat dijangkau: dev server harus listen di LAN IP Anda (--host 0.0.0.0), ponsel harus berada di jaringan yang sama, dan aplikasi memerlukan Jaringan Lokal izin (Settings > Privacy & Security > Local Network). Hapus server.url dari config sebelum release build.
• bundle Live update rusak: jika aplikasi memakai update OTA, bundle bermasalah bisa membuat layar blank. Updater Capgo akan rollback otomatis ketika notifyAppReady() tidak dipanggil tepat waktu. Lihat dokumentasi updater.

Konten di bawah notch atau home indicator

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

Keyboard menutupi input

Konfigurasikan Plugin Keyboard resize mode (native, body, ionic atau none) dan tes di perangkat fisik. Simulator menangani keyboard secara berbeda.

Error App Store Connect

• ITMS-91053: Missing API declaration: aplikasi atau plugin Anda menggunakan API yang memerlukan alasan (required-reason) tanpa entri privacy manifest. Tambahkan sebuah 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 pengaturan untuk app extension.

Cara debug jika error tidak terdaftar

1. Safari Web Inspector untuk error JS dan request jaringan. Debug build bisa di-inspect di iOS 16.4+. Untuk release build, atur ios.webContentsDebuggingEnabled: true untuk sementara.
2. Konsol Xcode untuk log native, termasuk log Capacitor ⚡️ pesan bridge yang menampilkan setiap pemanggilan plugin.
3. Console.app dengan perangkat yang dipilih 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.

Panduan panduan lengkap debugging app Capacitor membahas lebih dalam setiap tool. Jika akar masalahnya adalah bug plugin, patch biasanya cara tercepat untuk mengatasi hambatan sambil menunggu rilis.