Capacitor iOS Troubleshooting: Häufige Fehler und Lösungen

Die meisten Capacitor iOS-Probleme fallen in fünf Gruppen: falsche Toolchain, Dependency-Auflösung (SPM oder CocoaPods), Compile-Fehler durch Plugins, code Signing und Runtime-Probleme wie „plugin is not implemented“ oder ein leerer WebView. Beginne damit bunx cap doctor, stelle sicher, dass Xcode 26 ausgewählt ist, und führe bunx cap sync ios, und lies den ersten Fehler im Xcode-Buildlog, nicht den letzten.

Dieser Guide listet die Fehler, die in Capacitor 8 Projekten am häufigsten auftreten, ihre Ursachen und die jeweilige Lösung. Für Android siehe den Capacitor Android-Troubleshooting-Guide.

Schnelle Triage-Checkliste

Run these before chasing a specific error:

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

• Versionen: @capacitor/core, @capacitor/ios und @capacitor/cli müssen dieselbe Major-Version haben. Abweichungen führen zu seltsamen Compile- und Runtime-Fehlern. Siehe Capacitor Versions-Mismatch-Fehler beheben.
• Ein Xcode: Wenn du mehrere Xcode-Versionen hast, xcode-select -p entscheidet, welche Version CLI verwendet. Behebe das mit sudo xcode-select -s /Applications/Xcode.app.
• Welches Package-Management-Tool: falls ios/App/CapApp-SPM vorhanden ist, verwendet das Projekt SPM. Falls ios/App/Podfile vorhanden ist, verwendet es CocoaPods.

Toolchain-Fehler

Xcode oder SDK zu alt

Symptome: value of type 'WKWebView' has no member 'isInspectable', Swift-Syntaxfehler innerhalb von Capacitor, oder compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 benötigt Xcode 26. In GitHub Actions macos-latest verweist nicht immer auf das Image mit dem neuesten Xcode. Pinne ein Image, das Xcode 26 enthält, und wähle es explizit aus:

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

Prüfe die Runner-Image-Dokumentation für den exakten Pfad. Für den Module-Minimum-Fehler erhöhe das Deployment Target deiner App auf das Minimum des Plugins oder verwende eine ältere Plugin-Version.

ITMS-90725: SDK version issue beim Upload

Der Build wurde mit einem SDK erstellt, der älter ist als das, was Apple derzeit akzeptiert. Seit dem 28. April 2026 müssen Uploads mit Xcode 26 und dem iOS 26 SDK erstellt werden. Siehe Apples Xcode-26-Anforderung für Capacitor Apps. Capgo Build baut bereits mit Xcode 26, falls du keine Mac-Runner pflegen möchtest.

Swift Package Manager-Fehler

Missing package product 'CapApp-SPM'

Xcode hat das lokale Paket nicht aufgelöst oder der Cache ist veraltet.

1. File > Packages > Reset Package Caches.
2. Datei > Pakete > Paketversionen auflösen.
3. Falls die App von CocoaPods migriert wurde, prüfe, ob CapApp-SPM wird unter dem Projekt- Package Dependencies“ Tab hinzugefügt und mit dem App-Target verknüpft.

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

Ein Plugin Package.swift verwendet einen Package- oder Produktnamen, der nicht mit dem übereinstimmt, was Capacitor CLI aus seinem npm-Namen generiert hat. Dies ist ein Plugin-Bug. Aktualisiere das Plugin oder patche es. Plugin-Autoren finden die Namenskonvention in Migration eines Capacitor Plugins zu SPM.

„Some installed Capacitor plugins are not compatible with SPM“

Diese Warnung während cap sync bedeutet, dass mindestens ein Plugin kein Package.swift. Es wird aus der App ausgeschlossen, daher schlagen Aufrufe mit „nicht implementiert“ fehl. Plugin aktualisieren, durch eines ersetzen, das SPM unterstützt, oder vorübergehend CocoaPods verwenden.

Doppelte Paketidentität oder Zielname

Zwei Plugins teilen sich eine Package-Identität oder einen Target-Namen (oft ein generischer Name wie Plugin). Seit CLI 8.4 lässt sich das über die Capacitor Config beheben:

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

symlink bewirkt, dass CLI das Plugin über einen Symlink-Ordner mit eindeutigem Pfad referenziert. moduleAliases benennt ein kollidierendes Modul für diese Dependency um. Melde den Konflikt auch upstream.

Nicht bearbeiten CapApp-SPM/Package.swift

Die CLI schreibt sie bei jedem Sync neu. Lokale Änderungen gehen verloren. Nutze die experimental.ios.spm Config-Optionen stattdessen.

CocoaPods-Fehler

No such module 'Capacitor'

Du hast App.xcodeproj anstatt App.xcworkspace. Nutze bunx cap open ios geöffnet. Wenn der Workspace offen ist und der Fehler weiterhin besteht, führe bunx cap sync ios um Pods neu zu installieren.

CocoaPods could not find compatible versions for pod "X"

Zwei Ursachen:

1. Veraltetes Spec-Repo: ausführen cd ios/App && pod install --repo-update.
2. Konfliktierende Pins: Zwei Plugins benötigen inkompatible Versionen desselben Pods. Der Fehler gibt die Kette aus. Upgrade das Plugin mit dem strikten Pin, gleiche die Versionen an (bei Firebase alle Firebase-Plugins auf derselben SDK-Version halten) oder patche die Podspec.

Wenn es weiterhin fehlschlägt, lösche ios/App/Podfile.lock und ios/App/Pods, und synchronisiere erneut. Dies aktualisiert auch alle Pods, teste daher danach.

The sandbox is not in sync with the Podfile.lock

Ausführen bunx cap sync ios. Tritt nach Branch-Wechseln oder unvollständigen Installationen auf.

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

Dein project.pbxproj verwendet ein Format, das deine CocoaPods-Version nicht lesen kann. CocoaPods aktualisieren (brew upgrade cocoapods oder die Version in deiner Gemfile) erhöhen. Als letzte Option: Datei sichern und objectVersion.

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

Das User-Script-Sandboxing von Xcode blockiert das CocoaPods-Framework-Embed-Skript. Setzen Build-Einstellungen > User Script Sandboxing zu Nein im App-Target aktivieren.

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

Der Simulator-Build läuft für Intel. Auf Apple Silicon bedeutet das in der Regel, dass Xcode unter Rosetta oder einer älteren EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 Diese Einstellung stammt aus einem früheren Workaround. Führe Xcode nativ aus, entferne die Einstellung aus dem App-Target und allen post_install Hook, dann clean und rebuild.

Kompilierfehler

Command PhaseScriptExecution failed with a nonzero exit code

Dies ist ein Wrapper. Falteten Sie die fehlerhafte Build-Phase im Report-Navigator auf und lesen Sie die Skriptausgabe. Häufige Ursachen in Capacitor-Apps:

• Ein Run Script benötigt node und Xcode findet es nicht, weil Xcode dein Shell-Profil nicht lädt und Node über nvm, fnm oder Volta installiert ist. Verwende den vollen Pfad zu node im Skript oder exportiere PATH am Anfang des Skripts.
• Ein Crash-Reporting-Upload-Skript (Sentry, Crashlytics) hat in der CI keine Credentials.
• CocoaPods-Embed-Skript wird durch das User-Script-Sandboxing blockiert (siehe oben).

'X' is only available in iOS 16.0 or newer

Ein Plugin verwendet ein API über deinem Deployment Target. Erhöhe das Target in Xcode, in der Podfile (platform :ios, '16.0'), wenn du CocoaPods nutzt, und prüfe das Minimum im README des Plugins.

Swift 6-Konkurrenzfehler in einem Plugin

Meldungen wie Sending 'x' risks causing data races erscheinen, wenn ein Plugin oder dein App-Target den Swift 6 Language Mode verwendet. Capacitor 8 unterstützt Swift 6 offiziell nicht. Halte das App-Target im Swift 5 Language Mode, bis das Plugin aktualisiert wird.

Code Signing

Signing for "App" requires a development team

Öffne App-Target > Signing & Capabilities und wähle ein Team. In CI übergibst du DEVELOPMENT_TEAM zu xcodebuild oder ein Signierungstool verwenden. Wenn der Fehler einen Pod-Resource-Bundle statt der App benennt, deaktivieren Sie die Signierung für Bundle-Targets in der Podfile. post_install Hook.

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

Du hast eine Capability (Push Notifications, Associated Domains, Sign in with Apple) hinzugefügt, ohne das Profil neu zu generieren. Aktiviere sie im Apple Developer Portal unter App ID und aktualisiere dann die Profile. Unser iOS-Zertifikatsgenerator erleichtert das Erstellen von Zertifikaten ohne Mac-Keychain-Akrobatik, und die UDID-Finder hilft bei der Registrierung von Testgeräten.

Unable to install "App" auf dem Gerät

Aktiviere den Entwicklermodus auf dem Gerät (Einstellungen > Datenschutz & Sicherheit > Entwicklermodus), vertraue dem Entwicklerzertifikat und stelle sicher, dass die UDID des Geräts im Provisioning-Profil für Entwicklungsbauten enthalten ist.

Runtime-Fehler

"X" plugin is not implemented on ios

Die JavaScript-Seite hat keine native Implementierung gefunden. Prüfe in dieser Reihenfolge:

1. Das Plugin befindet sich in package.json und du hast bunx cap sync ios nach der Installation ausgeführt.
2. Für SPM: Das Plugin erscheint in ios/App/CapApp-SPM/Package.swift. Falls nicht, hat es keine Package.swift.
3. Für CocoaPods: Das Plugin erscheint im capacitor_pods Block der Podfile und pod install hatte keine Warnungen ausgegeben.
4. Du hast nicht zwei Plugins, die denselben JS-Namen registrieren (z. B. zwei Push-Benachrichtigungs-Plugins).
5. WKAppBoundDomains ist nicht in Info.plist, oder wenn doch, limitsNavigationsToAppBoundDomains gesetzt ist und localhost ist aufgeführt. App-gebundene Domains blockieren andernfalls die Plugin-Skript-Injektion.
6. Build-Ordner bereinigen und neu bauen. Veraltete Builds behalten alte Plugin-Registrierungen bei.

Leerer weißer Bildschirm beim Start

Prüfe zuerst den WebView mit dem Safari Web Inspector. Die meisten leeren Bildschirme sind ein JavaScript-Fehler.

• Falsch webDir: capacitor.config.ts verweist auf einen Ordner, der nicht enthält index.html. Prüfe ios/App/App/public.
• Build-Target zu neu: Dein Bundler erzeugt Syntax, die ältere WebKit-Versionen nicht unterstützen. iOS 15 ist das Minimum für Capacitor 8, also target safari15 oder neuer in Vite/esbuild und prüfe deine browserslist.
• Absolute Asset-Pfade: ein base auf ein CDN oder einen Subpfad in deiner Bundler-Konfiguration gesetzt, bricht das lokale Laden.
• Live Reload nicht erreichbar: Der Dev-Server muss auf deiner LAN-IP lauschen (--host 0.0.0.0), das Telefon muss im selben Netzwerk sein und die App benötigt die Lokales Netzwerk Berechtigung (Einstellungen > Datenschutz & Sicherheit > Lokales Netzwerk). Entfernen server.url aus der Konfiguration vor Release-Builds.
• Live update Bundle defekt: Wenn die App OTA-Updates verwendet, kann ein fehlerhaftes Bundle den Bildschirm leeren. Capgo’s Updater rollt automatisch zurück, wenn notifyAppReady() nicht rechtzeitig aufgerufen wird. Siehe die Updater-Docs.

Inhalte unter dem Notch oder Home-Indicator

Füge viewport-fit=cover zu Ihrem Viewport-Meta-Tag und füllen Sie mit env(safe-area-inset-top) und env(safe-area-inset-bottom). Capacitor 8’s System Bars-Plugin steuert Stil und Sichtbarkeit der Statusleiste auf beiden Plattformen.

Tastatur bedeckt Eingabefelder

Konfiguriere Keyboard-Plugin resize Modus (native, body, ionic oder none) und auf einem echten Gerät testen. Simulatoren behandeln die Tastatur anders.

App Store Connect-Fehler

• ITMS-91053: Missing API declaration: Deine App oder ein Plugin verwendet einen required-reason API ohne Eintrag im Privacy Manifest. Füge eine PrivacyInfo.xcprivacy zum App-Target mit den Gründen hinzu und aktualisiere Plugins, die ein eigenes Manifest mitliefern.
• ITMS-90725: SDK version issue: Mit Xcode 26 neu bauen.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': Ein Framework ist in einer Extension oder einem anderen Framework eingebettet. Prüfe Embed Einstellungen für App-Extensions.

Debuggen, wenn der Fehler nicht aufgeführt ist

1. Safari Web Inspector für JS-Fehler und Netzwerkaufrufe. Debug-Builds sind ab iOS 16.4+ inspizierbar. Für Release-Builds setzen Sie ios.webContentsDebuggingEnabled: true temporär.
2. Xcode-Konsole für native Logs, einschließlich der von Capacitor ⚡️ Bridge-Nachrichten, die jeden Plugin-Aufruf anzeigen.
3. Konsole.app mit dem ausgewählten Gerät für Crash- und Systemlogs.
4. Isolieren: Erstellen Sie eine neue App mit bun create @capacitor/app, füge nur das verdächtige Plugin hinzu und prüfe, ob der Fehler erneut auftritt.

Der Der ultimative Guide zum Debugging von Capacitor-Apps geht auf jedes Tool genauer ein. Wenn die Ursache ein Plugin-Bug ist, ist ein Patch ist meistens die schnellste Lösung, um bis zum Release weiterzuarbeiten.