Schadensbegrenzung

Lösungen für häufige Probleme bei der Erstellung von nativen Apps mit Capgo Cloud Build.

Build-Fehler

“Upload fehlgeschlagen” oder “Verbindungstimeout”

Symptoms:

• Build fails during project upload
• Die Erstellung der App scheitert während des Uploads

Solutions:

1. Überprüfen Sie Ihre Internetverbindung

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. Projektsgröße reduzieren

   • Ensure node_modules/ wird nicht hochgeladen (sollte automatisch ausgeschlossen werden)
   • Überprüfen Sie nach großen Dateien in Ihrem Projekt:

   find . -type f -size +10M

3. Überprüfen Sie die Ablaufzeit der Upload-URL

   • Upload-URLs erlöschen nach 1 Stunde
   • If you get an expired URL error, re-run the build command

Tipp

Große Projekte können die Buildzeitbegrenzung erreichen (siehe Bekannte Einschränkungen). Kontaktieren Sie das Support-Team für Unternehmensoptionen.

„Build-Time-Out nach 10 Minuten“

Symptome:

• Buildzeit überschreitet die maximale erlaubte Zeit
• Status zeigt timeout

Lösungen:

1. Optimieren Sie Abhängigkeiten

   • Entfernen Sie nicht benötigte npm-Pakete
   • Use npm prune --production vor der Erstellung

2. Überprüfen Sie Netzwerkprobleme beim Aufbau

   • Einige Abhängigkeiten können während der Erstellung große Dateien herunterladen
   • Erwägen Sie eine Vorkachelung mit einem Lock-File

3. Überprüfen Sie native Abhängigkeiten

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. Kontaktieren Sie den Support

   • Wenn Ihr App legitim mehr Zeit benötigt
   • Wir können Grenzen für bestimmte Anwendungsfälle anpassen

Authentifizierungsprobleme

“API Schlüssel ungültig” oder “Nicht autorisiert”

Symptome:

• Der Build scheitert sofort mit einer Authentifizierungsfehler
• 401- oder 403-Fehler

Lösungen:

1. Überprüfen Sie, ob der API-Schlüssel korrekt ist

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. Überprüfen Sie die Berechtigungen des API-Schlüssels

   • Der Schlüssel muss write oder all Rechte
   • Überprüfen Sie in Capgo-Dashboard unter API Schlüsseln

3. Stellen Sie sicher, dass der API-Schlüssel gelesen wird

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. Re-authenticate

   bunx @capgo/cli@latest login

"App nicht gefunden" oder "Keine Berechtigung für diese App"

Symptome:

• Authentifizierung funktioniert, aber App-spezifische Fehler

Lösungen:

1. Überprüfen Sie, ob die App registriert ist

   bunx @capgo/cli@latest app list

2. Überprüfen Sie, ob die App-ID übereinstimmt

   • Überprüfen Sie capacitor.config.json appId
   • Ensure command uses correct app ID

3. Überprüfen Sie die Zugriffsrechte der Organisation

   • Check you’re in the correct organization
   • Die API-Schlüssel muss Zugriff auf die Organisation der App haben

iOS-Bau-Probleme

“Code Signierung fehlgeschlagen”

Symptome:

• Der Build fehlschlägt während der code Signierungsphase
• Xcode-Fehler über Zertifikate oder Profile

Lösungen:

1. Überprüfe, ob Zertifikatstyp dem Buildtyp entspricht

   • Entwicklungsbuilds benötigen Entwicklungszertifikate
   • App-Store-Builds benötigen Verteilungszertifikate

2. Überprüfe Zertifikat und Profil auf Übereinstimmung

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. Ensure provisioning profile is valid

   • Überprüfen Sie die Ablaufzeit
   • Stellen Sie sicher, dass es Ihren App-Id enthält
   • Bestätigen Sie, dass es Ihren Zertifikat enthält

4. Regenerieren Sie die Anmeldeinformationen

   • Löschen Sie das alte Zertifikat/Profil
   • Erstellen Sie neue in Apple Developer-Portal
   • Neu kodieren und Umgebungsvariablen aktualisieren

„Das Bereitstellungsprofil enthält kein Signierungszertifikat“

Symptome:

• Xcode kann keine Zertifizung in Profil finden

Lösungen:

1. Download neuestes Profil von Apple

   • Gehe zu Apple Developer → Zertifikate, IDs und Profile
   • Download Provisioning-Profil
   • Stelle sicher, dass es dein Zertifikat enthält

2. Überprüfe das Zertifikat im Profil.

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. In Apple Developer-Portal bearbeite Profil

   • In Apple-Entwickler-Portal, Profil bearbeiten
   • Stellen Sie sicher, dass Ihre Distribution-Zertifizierung ausgewählt ist
   • Herunterladen und erneut kodieren

„App Store Connect-Authentifizierung fehlgeschlagen“

Symptome:

• Upload auf TestFlight fehlschlägt
• Fehler bei der API-Schlüssel

Lösungen:

1. Überprüfen Sie die API-Schlüssel-Zertifikate

   • Überprüfen Sie APPLE_KEY_ID (soll 10 Zeichen lang sein)
   • Überprüfen Sie APPLE_ISSUER_ID (soll im UUID-Format sein)
   • Überprüfen Sie, ob APPLE_KEY_CONTENT korrekt base64-codiert ist

2. Synchronisieren Sie den Computer-Zeitpunkt

   • App Store Connect-Authentifizierung verwendet JWTs mit kurzer Gültigkeit, die aus Ihrem lokalen Systemzeit generiert werden
   • Der Apple-Server lehnt Token ab, die mehr als 20 Minuten in der Zukunft ablaufen, sodass auch kleine Uhrfehler einen sonst gültigen Schlüssel zum Scheitern bringen können.
   • Auf Windows öffnen Sie Einstellungen > Zeit und Sprache > Datum und Uhrzeit klicken Sie Sync now
   • Auf macOS öffnen Sie Systemeinstellungen > Allgemein > Datum und Uhrzeit und aktivieren Sie die automatische Zeit
   • Auf Linux überprüfen Sie timedatectl status und aktivieren Sie NTP, wenn erforderlich
   • After syncing, re-run the Capgo build or credential command

   Siehe Apples Erstellen Sie Token für API-Anforderungen. Dokumentation für die Lebensdauerregel des App Store Connect-Tokens.

3. Testen Sie die API-Schlüssel lokal.

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. Überprüfen Sie die Berechtigungen für den API-Schlüssel.

   • Key needs “Developer” role or higher
   • Überprüfen Sie in App Store Connect -> Benutzer und Zugriff -> Schlüssel.

5. Stelle sicher, dass die Schlüssel nicht zurückgezogen wurden.

   • Überprüfen Sie in App Store Connect.
   • Erstellen Sie einen neuen Schlüssel, wenn erforderlich.

App stürzt auf iOS 27 beim Start ab

Symptome:

• Die mit Xcode 27 erstellte App schließt sich sofort auf iOS 27 (TestFlight oder Gerät)
• Der Crashbericht zeigt _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Lösung: Apps, die mit iOS 27 SDK erstellt wurden, müssen sich an das UIScene-Lifecycle anpassen. Fügen Sie ein SceneDelegate und ein UIApplicationSceneManifest zur ios/App/App/Info.plistoder bauen Sie mit --xcode-version 26Capgo , der diese Builds vor dem Start blockiert (Prüfung vor der Ausführung) ios/plist-scene-lifecycle-xcode27).

Pod-Install fehlgeschlagen

Vorsicht

Capgo Ab Dezember 2026 stoppt die Capgo-Bauanlage die CocoaPods-Projekte. Migrieren Sie zum Swift Package Manager: siehe den Capacitor Leitfaden zum SPM.

Symptome:

• Die Bauanlage fehlt während der CocoaPods-Installation
• Podfile-Fehler

Lösungen:

1. Überprüfe, dass Podfile.lock im Repository committet ist.

   git status ios/App/Podfile.lock

2. Test lokale pod installieren

   cd ios/App
   pod install

3. Überprüfe auf inkompatible Pods

   • Überprüfe Podfile auf Versionskonflikte
   • Stellen Sie sicher, dass alle Pods Ihr iOS-Zielsystem unterstützen

4. Lösche den Pod-Cache

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Android-Bau-Probleme

„Falsches Keystore-Passwort“

Symptome:

• Der Build scheitert während des Signierens
• Gradle-Fehler über das Keystore

Lösungen:

1. Überprüfen Sie das Keystore-Passwort

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. Überprüfen Sie die Umgebungsvariablen

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Überprüfen Sie die Base64-Codierung

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

„Alias nicht gefunden“

Symptome:

• Das Signieren fehlt mit Aliasfehler

Lösungen:

1. Liste der Keystore-Aliase

   keytool -list -keystore my-release-key.keystore

2. Überprüfe, ob der Alias genau übereinstimmt

   • Der Alias ist case-sensitive
   • Überprüfen Sie die Tippfehler in KEYSTORE_KEY_ALIAS

3. Verwenden Sie die richtige Alias aus dem Keystore

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

„Gradle-Build fehlgeschlagen“

Symptome:

• Allgemeine Gradle-Fehler
• Komplettierungs- oder Abhängigkeitsprobleme

Lösungen:

1. Testen Sie die lokale Build vorher

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Überprüfen Sie fehlende Abhängigkeiten

   • Überprüfen Sie die build.gradle-Dateien
   • Ensure all plugins are listed in dependencies

3. Überprüfen Sie die Kompatibilität der Gradle-Version

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Löschen Sie den Gradle-Cache

   cd android
   ./gradlew clean
   rm -rf .gradle build

„Play Store-Upload fehlgeschlagen“

Symptome:

• Der Build gelingt, aber die Upload-Fehler treten auf
• Dienstkontenfehler

Lösungen:

1. Überprüfen Sie die Dienstkonten-JSON-Datei

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Überprüfen Sie die Dienstkontenberechtigungen

   • Go to Play Console → Setup → API Access
   • Stellen Sie sicher, dass das Dienstkonto Zugriff auf Ihre App hat
   • Erlaubnis für "Freigabe in Testtracks" erteilen

3. Verify app is set up in Play Console

   • Die App muss zuerst im Google Play Console erstellt werden
   • Zumindest ein APK muss manuell zuerst hochgeladen werden

4. Überprüfen Sie, ob API aktiviert ist

   • Google Play Developer API muss aktiviert sein
   • Überprüfen Sie im Google Cloud Console

Allgemeine Probleme

„Job nicht gefunden“ oder „Build-Status nicht verfügbar“

Symptome:

• Der Build-Status kann nicht überprüft werden
• Fehler bei der Job-ID

Lösungen:

1. Warten Sie einen Moment und versuchen Sie es erneut

   • Die Build-Jobs können einige Sekunden zum Initialisieren benötigen

2. Überprüfen Sie, ob die Job-ID korrekt ist

   • Überprüfen Sie die Job-ID aus der ersten Build-Antwort

3. Überprüfe, ob das Build nicht abgelaufen ist

   • Die Build-Daten sind 24 Stunden verfügbar

„Projekt-Synchronisation fehlgeschlagen“

Symptome:

• Die Build schlägt vor der Kompilierung fehl
• Dateimangel-Fehler

Lösungen:

1. Führen Sie Capacitor lokal synchron

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Überprüfe native Dateien auf der Git-Ignore-Liste

   • Überprüfen Sie die .gitignore-Datei
   • Ensure important config files aren’t ignored

“Aufbau erfolgreich, aber ich sehe keine Ausgabe”

Symptome:

• Der Build zeigt Erfolg, aber kein Downloadlink

Lösungen:

1. Überprüfe die Build-Konfiguration

   • Die Artefakt-Speicherung mag nicht konfiguriert sein
   • Kontaktiere den Support, wenn der Zugriff auf dein Artefakt nicht verfügbar ist.

2. Für die iOS-Testflug-Abgabe

   • Für iOS-Testflug-Submission
   • Die Verarbeitung kann nach dem Hochladen 5-30 Minuten dauern.

3. Für den Google Play Store

   • Überprüfe Play Console → Testen → Internes Testen
   • Die Verarbeitung kann einige Minuten dauern.

Build erfolgreich, aber Artefakt falsch nach Umgebungswechsel

Symptome:

• Build-Status ist success aber das IPA/AAB/APK passt nicht zur gerade erst gebauten Branch oder Flavor
• Android AAB fehlt oder ist falsch nach Wechsel von RC- vs. Produktionszertifikaten oder --android-flavor
• Build schließt sich verdächtig schnell nach Änderung der Signierungs-Konfiguration oder Produktflavor

Ursache: Capgo setzt die pro-App- Build-Cache durch Standard (auslassen cache_key für den gemeinsamen allgemeinen Cache). Wenn RC und Produktionszertifikate denselben App-Id ohne separate Schlüssel teilen, kann eine Wiederherstellung auf die vorherige Umgebung zurückgreifen.

Lösungen:

1. Verwenden Sie eine Cache-Schlüssel pro Umgebung (empfohlen für laufende RC/PROD Pipelines):

   # Production
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=prod \
     --android-flavor production
   
   # Staging / RC
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=staging \
     --android-flavor staging

2. Zwingen Sie eine saubere Build durchzuführen wenn Sie debuggen:

   bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

3. In API oder Webhook-Integrationenpassen Sie cache_key zum Beispiel "prod") oder setzen cache_enabled: false für eine einzelne saubere Ausführung.

Siehe Build Cache für die vollständige Optionenverweis.

CI/CD-Spezifische Probleme

GitHub Aktionen: “Befehl nicht gefunden”

Symptome:

• bunx @capgo/cli@latest … fehlschlägt in CI mit “Befehl nicht gefunden”

Lösungen:

1. Stellen Sie Bun zuerst ein so bunx ist verfügbar:

   - uses: oven-sh/setup-bun@v2

2. Dann führen Sie den CLI aus — bunx holt es auf Abruf, keine globale Installation erforderlich:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub Aktionen: „Geheime Daten nicht gefunden“

Symptome:

• Umgebungsvariablen leer in der Build

Lösungen:

1. Überprüfen Sie, ob Geheimnisse gesetzt sind

   • Gehe zu Repository-Einstellungen → Geheimnisse und Variablen → Aktionen
   • Füge alle erforderlichen Geheimnisse hinzu

2. Verwende die richtige Syntax

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. Überprüfe, ob Geheimnisnamen übereinstimmen

   • Die Namen sind case-sensitive
   • Keine Tippfehler in den Geheimnisverweisen

Erhalte mehr Hilfe

Verbose Logging aktivieren

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Fehlermeldungen und Build-Informationen sammeln

When contacting support, include:

1. Der verwendete Build-Befehl

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. Der Fehlermeldung Die vollständige Ausgabe

3. Die Job-ID Die Job-ID (aus der Ausgabemeldung)

4. Buildprotokolle (komplett Terminalausgabe kopieren)

5. Umgebungsinfo

   node --version
   npm --version
   bunx @capgo/cli@latest --version

Kontakt Support

• Discord: Unsere Community beitreten
• E-Mail: support@capgo.app
• Dokumentation: Capgo Docs

Bekannte Einschränkungen

aktuelle Einschränkungen:

• Höchstzeit für die Erstellung: 10 Minuten
• Höchstgröße für das Hochladen: ~500 MB
• iOS-Builds erfordern 24-Stunden-Mac-Mietverträge, Mac-Builds werden in der Warteschlange platziert, um die Nutzung zu optimieren.
• Die Verfügbarkeit von Build-Artefakten hängt von der Build-Ziel- und Artefakt-Speicher-Konfiguration ab

Diese Einschränkungen können aufgrund von Feedback angepasst werden

Prescan hat meine Erstellung blockiert

Capgo führt eine lokale Vorabscannung Bevor Sie hochladen. Korrigieren Sie das gemeldete Problem oder ignorieren Sie nur diese Prüfung, ID:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

Siehe das vollständige Katalog: Prüfungsvorabscannungen.

Zusätzliche Ressourcen

• Getting Started - Anleitung zur ersten Einrichtung
• Konfigurationsoptionen - CLI Flags einschließlich --cache-key und --no-cache
• iOS-Builds - iOS-spezifische Konfiguration
• Android-Builds - Android-spezifische Konfiguration
• Prescan-Überprüfungen - Vollständige Liste der Vorbau-Überprüfungen und Ignorier-Flags
• CLI Referenz - Vollständige Befehlsdokumentation