Dépannage Capacitor iOS : erreurs courantes et solutions

La plupart des problèmes iOS avec Capacitor se répartissent en cinq catégories : une toolchain incorrecte, la résolution des dépendances (SPM ou CocoaPods), des erreurs de compilation dues aux plugins, la signature de code, et des problèmes au runtime comme « plugin is not implemented » ou une WebView vide. Commencez par bunx cap doctor, confirmez que Xcode 26 est sélectionné, puis lancez bunx cap sync ios, et lisez la première erreur dans le log de build Xcode, pas la dernière.

Ce guide répertorie les erreurs les plus fréquentes dans les projets Capacitor 8, leurs causes et leurs solutions. Pour Android, consultez le guide de dépannage Android de Capacitor.

Checklist de triage rapide

Exécutez ces commandes avant de chercher une erreur précise :

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

• Versions: @capacitor/core, @capacitor/ios et @capacitor/cli must share the same major. Mismatches cause odd compile and runtime errors. See corriger les erreurs de version Capacitor.
• Un Xcode: si vous avez plusieurs versions de Xcode, xcode-select -p détermine lequel est utilisé par CLI. Corrigez-l’avec sudo xcode-select -s /Applications/Xcode.app.
• Quel gestionnaire de paquets: si ios/App/CapApp-SPM existe, le projet utilise SPM. Si ios/App/Podfile existe, il utilise CocoaPods.

Erreurs de toolchain

Xcode ou SDK trop ancien

Symptômes : value of type 'WKWebView' has no member 'isInspectable', erreurs de syntaxe Swift dans Capacitor, ou compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 nécessite Xcode 26. Dans GitHub Actions, macos-latest ne pointe pas toujours vers l’image avec le Xcode le plus récent. Épinglez une image qui inclut Xcode 26 et sélectionnez-l’explicitement :

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

Consultez la doc de l’image du runner pour le chemin exact. Pour l’erreur de version minimale du module, augmentez la cible de déploiement de votre app au minimum requis par le plugin, ou utilisez une version antérieure du plugin.

ITMS-90725: SDK version issue à l’upload

Le build a été réalisé avec un SDK plus ancien que ce qu’Apple accepte actuellement. Depuis le 28 avril 2026, les uploads doivent être compilés avec Xcode 26 et le SDK iOS 26. Voir Xcode 26 désormais exigé par Apple pour les apps Capacitor. Build Capgo compile déjà sur Xcode 26 si vous ne voulez pas maintenir de runners Mac.

Erreurs Swift Package Manager

Missing package product 'CapApp-SPM'

Xcode n’a pas résolu le package local, ou son cache est obsolète.

1. File > Packages > Reset Package Caches.
2. Fichier > Packages > Résoudre les versions des packages.
3. Si l’application a été migrée depuis CocoaPods, vérifiez que CapApp-SPM est ajouté dans l’onglet Dépendances du package du projet et lié à la cible App.

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

Un Package.swift plugin utilise un nom de package ou de produit qui ne correspond pas à ce que Capacitor CLI a généré à partir de son nom npm. Il s’agit d’un bug du plugin. Mettez à jour le plugin, ou le patcher. Les auteurs de plugins peuvent trouver la règle de nommage dans migrer un plugin Capacitor vers SPM.

« Certains plugins Capacitor installés ne sont pas compatibles avec SPM »

Cet avertissement cap sync signifie qu’au moins un plugin n’a pas de Package.swift. Il est exclu de l’app, donc les appels vers celui-ci échouent avec « not implemented ». Mettez à jour le plugin, remplacez-le par un plugin compatible SPM, ou utilisez CocoaPods pour l’instant.

Identité de package ou nom de cible en double

Deux plugins partagent une identité de package ou un nom de cible (souvent un nom générique comme Plugin). Depuis CLI 8.4, vous pouvez le corriger depuis la config Capacitor :

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

symlink fait pointer CLI vers le plugin via un dossier symlink avec un chemin unique. moduleAliases renomme un module en conflit pour cette dépendance. Signalez aussi le conflit en amont.

Ne pas modifier CapApp-SPM/Package.swift

Le CLI le réécrit à chaque synchronisation. Les modifications locales disparaissent. Utilisez le experimental.ios.spm options de configuration.

Erreurs CocoaPods

No such module 'Capacitor'

Vous avez ouvert App.xcodeproj au lieu de App.xcworkspace. Utilisez bunx cap open ios. Si le workspace est ouvert et que l’erreur persiste, exécutez bunx cap sync ios pour réinstaller les pods.

CocoaPods could not find compatible versions for pod "X"

Deux causes :

1. Repo de specs obsolète : exécuter cd ios/App && pod install --repo-update.
2. Pins en conflit: deux plugins nécessitent des versions incompatibles du même pod. L’erreur affiche la chaîne. Mettez à niveau le plugin avec le pin strict, alignez les versions (pour Firebase, gardez tous les plugins Firebase sur la même version SDK), ou patchez le podspec.

Si ça continue d’échouer, supprimez ios/App/Podfile.lock et ios/App/Pods, puis resynchronisez. Cela met aussi à niveau tous les pods, pensez à tester ensuite.

The sandbox is not in sync with the Podfile.lock

Exécutez bunx cap sync ios. Cela arrive après des changements de branche ou des installations partielles.

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

Votre project.pbxproj utilise un format que votre version de CocoaPods ne peut pas lire. Mettez à jour CocoaPods (brew upgrade cocoapods ou augmentez-la dans votre Gemfile). En dernier recours, sauvegardez le fichier et réduisez objectVersion.

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

Le sandboxing des scripts utilisateur d’Xcode bloque le script d’intégration des frameworks CocoaPods. Définissez Build Settings > User Script Sandboxing vers Non sur la cible App.

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

Le build du simulateur s’exécute pour Intel. Sur Apple Silicon, cela signifie généralement que Xcode tourne sous Rosetta ou une ancienne EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 ce paramètre provient d'une ancienne solution de contournement. Lancez Xcode nativement, supprimez ce paramètre de la cible App et de tout post_install hook, puis nettoyez et recompilez.

Erreurs de compilation

Command PhaseScriptExecution failed with a nonzero exit code

Ceci est un wrapper. Dépliez la phase de build en échec dans le Report navigator et lisez la sortie du script. Causes fréquentes dans les apps Capacitor :

• Un Run Script nécessite node et Xcode ne le trouve pas, car Xcode ne charge pas votre profil shell et Node est installé avec nvm, fnm ou Volta. Utilisez le chemin complet vers node dans le script, ou exportez PATH au début de celui-ci.
• Un script d'upload de crash reporting (Sentry, Crashlytics) n'a pas d'identifiants en CI.
• Le script d'embed CocoaPods est bloqué par l’user script sandboxing (voir ci-dessus).

'X' is only available in iOS 16.0 or newer

Un plugin utilise un API supérieur à votre cible de déploiement. Augmentez la cible dans Xcode, dans le Podfile (platform :ios, '16.0') si vous utilisez CocoaPods, et vérifiez le README du plugin pour connaître son minimum.

Erreurs de concurrence Swift 6 dans un plugin

Des messages comme Sending 'x' risks causing data races apparaissent lorsqu'un plugin ou la cible de votre app utilise le mode de langage Swift 6. Capacitor 8 ne prend pas officiellement en charge Swift 6. Gardez la cible App en mode de langage Swift 5 jusqu'à la mise à jour du plugin.

Signature Code

Signing for "App" requires a development team

Ouvrez Cible de l’app > Signing & Capabilities et choisissez une équipe. En CI, passez DEVELOPMENT_TEAM vers xcodebuild ou utilisez un outil de signature. Si l’erreur concerne un bundle de ressources pod plutôt que l’App, désactivez la signature pour les cibles bundle dans le Podfile post_install hook.

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

Vous avez ajouté une capability (Push Notifications, Associated Domains, Sign in with Apple) sans régénérer le profil. Activez-la sur l’App ID dans le portail Apple Developer, puis actualisez les profils. Notre Générateur de certificats iOS permet de créer des certificats sans manipuler la trousse de clés Mac, et Recherche d’UDID permet d’enregistrer les appareils de test.

Unable to install "App" sur l'appareil

Activez le mode développeur sur l’appareil (Réglages > Confidentialité et sécurité > Mode développeur), faites confiance au certificat du développeur et vérifiez que l’UDID de l’appareil figure dans le profil de provisionnement pour les builds de développement.

Erreurs au runtime

"X" plugin is not implemented on ios

Le côté JavaScript n’a trouvé aucune implémentation native. Vérifiez dans cet ordre :

1. Le plugin est dans package.json et vous avez lancé bunx cap sync ios après l’avoir installé.
2. Pour SPM : le plugin apparaît dans ios/App/CapApp-SPM/Package.swift. Sinon, il n’a pas de Package.swift.
3. Pour CocoaPods : le plugin apparaît dans le capacitor_pods bloc du Podfile et pod install n'a affiché aucun avertissement.
4. Vous n’avez pas deux plugins qui enregistrent le même nom JS (par exemple, deux plugins de notification push).
5. WKAppBoundDomains n’est pas dans Info.plist, ou si c’est le cas, limitsNavigationsToAppBoundDomains est défini et que localhost est listé. Sinon, les domaines app-bound bloquent l’injection de scripts du plugin.
6. Nettoyez le dossier de build et relancez le build. Les builds obsolètes gardent les anciens enregistrements.

Écran blanc au lancement

Inspectez d’abord la WebView avec Safari Web Inspector. La plupart des écrans blancs sont dus à une erreur JavaScript.

• Incorrect webDir: capacitor.config.ts pointe vers un dossier qui ne contient pas index.html. Vérifiez ios/App/App/public.
• Cible de build trop récente: votre bundler émet une syntaxe que les anciennes versions de WebKit ne prennent pas en charge. iOS 15 est la version minimale pour Capacitor 8, donc ciblez safari15 ou version ultérieure dans Vite/esbuild, et vérifiez votre browserslist.
• Chemins absolus des assets: un base définir une CDN ou un sous-chemin dans la configuration de votre bundler casse le chargement local.
• Live reload inaccessible: le serveur de développement doit écouter sur votre IP LAN (--host 0.0.0.0), le téléphone doit être sur le même réseau, et l’app doit disposer de l’accès au Réseau local permission (Réglages > Confidentialité et sécurité > Réseau local). Supprimez-la server.url de la configuration avant les builds de release.
• Bundle Live update corrompu: si l’app utilise des mises à jour OTA, un bundle défectueux peut vider l’écran. Le module de mise à jour de Capgo effectue un rollback automatique lorsque notifyAppReady() n’est pas appelé à temps. Consultez la la doc de l'updater.

Contenu sous le notch ou l’indicateur d’accueil

Ajoutez viewport-fit=cover à votre balise meta viewport et ajoutez un padding avec env(safe-area-inset-top) et env(safe-area-inset-bottom). Le plugin System Bars de Capacitor 8 contrôle le style et la visibilité de la barre d’état sur les deux plateformes.

Le clavier masque les champs

Configurez la Plugin clavier resize mode (native, body, ionic ou none) et testez sur un appareil réel. Les simulateurs gèrent le clavier différemment.

Erreurs App Store Connect

• ITMS-91053: Missing API declaration: votre application ou un plugin utilise une raison requise API sans entrée dans le manifeste de confidentialité. Ajoutez une PrivacyInfo.xcprivacy à la cible App avec les motifs, et mettez à jour les plugins qui embarquent leur propre manifeste.
• ITMS-90725: SDK version issue: recompilez avec Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': un framework est intégré dans une extension ou un autre framework. Vérifiez les réglages Intégrer pour les extensions d'app.

Comment déboguer quand l'erreur n'est pas listée

1. Inspecteur Web de Safari pour les erreurs JS et les appels réseau. Les builds de debug sont inspectables sur iOS 16.4+. Pour les builds de release, configurez ios.webContentsDebuggingEnabled: true temporairement.
2. Console Xcode pour les logs natifs, y compris ceux de Capacitor ⚡️ qui affichent chaque appel de plugin.
3. Console.app avec l'appareil sélectionné pour les logs système et de crash.
4. Isoler: créez une nouvelle app avec bun create @capacitor/app, ajoutez uniquement le plugin suspect, et voyez si l'erreur se reproduit.

Le Guide ultime pour déboguer les applications Capacitor détaille chaque outil. Si la cause racine est un bug de plugin, un patch est généralement le moyen le plus rapide de débloquer la situation en attendant la release.