Problembehandlung

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

Build-Fehler

„Hochladen fehlgeschlagen“ oder „Verbindungstimeout“

Symptome:

• Projektupload fehlt
• Zeitüberschreitung nach 60 Sekunden

Lösungen:

1. Überprüfen Sie Ihre Internetverbindung

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

2. Projektsgröße reduzieren

   • Stellen Sie sicher node_modules/ wird nicht hochgeladen (sollte automatisch ausgeschlossen werden)
   • Überprüfen Sie Ihre Projektdateien auf große Dateien:

   find . -type f -size +10M

3. Überprüfe die Gültigkeitsdauer der Upload-URL

   • URLs werden nach 1 Stunde abgelaufen.
   • Wenn Sie eine abgelaufene URL-Fehlermeldung erhalten, führen Sie den Build-Befehl erneut aus.

Tipp

Sehr große Projekte können die Buildzeitgrenze erreichen (siehe Bekannte EinschränkungenKontaktieren Sie den Support für Unternehmensoptionen.

Zeitüberschreitung nach 10 Minuten

Symptome:

• Der Build überschreitet die maximale erlaubte Zeit.
• Status zeigt an timeout

Lösungen:

1. Optimieren Sie Abhängigkeiten

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

2. Überprüfen Sie Netzwerkprobleme bei der Erstellung

   • Einige Abhängigkeiten können während der Erstellung große Dateien herunterladen
   • Betrachten Sie eine Vorab-Caching 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. Kontakt zum 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:

• Die Verarbeitung der App scheitert sofort an einer Authentifizierungsfehler
• Fehler 401 oder 403

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üfe die Berechtigungen für die API-Schlüssel

   • Der Schlüssel muss write oder all Berechtigungen haben
   • Überprüfe in der Capgo-Oberfläche unter API Schlüsseln

3. Stelle 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. Neu anmelden

   bunx @capgo/cli@latest login

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

Symptome:

• Authentifizierung funktioniert, aber Anwendungsspezifische Fehler

Lösungen:

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

   bunx @capgo/cli@latest app list

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

   • Überprüfen capacitor.config.json appId
   • Stellen Sie sicher, dass die Befehlszeile den richtigen App-ID verwendet

3. Überprüfen Sie den Zugriff auf die Organisation

   • Überprüfen Sie, ob Sie sich in der richtigen Organisation befinden
   • API Schlüssel muss Zugriff auf die App-Organisation haben

iOS-Bau-Probleme

„Code Signieren fehlgeschlagen“

Symptome:

• Der Aufbau fehlschlägt während der code-Signierungsphase
• Xcode-Fehler bezüglich Zertifikate oder Profile

Lösungen:

1. Überprüfen Sie, ob der Zertifikatstyp dem Buildtyp entspricht

   • Entwicklungsbuilds benötigen Entwicklungs-Zertifikate
   • App Store Builds benötigen Verteilungs-Zertifikate

2. Überprüfen Sie, ob Zertifikat und Profil übereinstimmen

   # 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. Stellen Sie sicher, dass das Provisioning-Profil gültig ist

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

4. Regenerieren Sie die Anmeldeinformationen

   • Löschen Sie das alte Zertifikat/Profil
   • Erstellen Sie neue im Apple Developer-Portal
   • Re-encode und Umgebungsvariablen aktualisieren

Provisioning-Profil enthält kein Signaturzertifikat

Symptome:

• Xcode kann kein Zertifikat im Profil finden

Lösungen:

1. Download des neuesten Profils von Apple

   • Gehe zu Apple Developer → Zertifikate, IDs und Profile
   • Download des Provisioning-Profils
   • Stellen Sie sicher, dass es Ihr Zertifikat enthält

2. Überprüfen Sie, ob das Zertifikat im Profil ist

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

3. Mit dem richtigen Zertifikat erneut Profil erstellen

   • Im Apple-Entwicklerportal, Profil bearbeiten
   • Stellen Sie sicher, dass Ihr Verteilungszertifikat ausgewählt ist
   • Herunterladen und erneut kodieren

”App Store Connect authentication failed”

Symptome:

• Hochladen auf TestFlight fehlschlägt
• API-Schlüsselfehler

Lösungen:

1. Überprüfen Sie die API-Schlüsselkredenziale

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

2. Synchronisieren Sie die Uhr Ihres Computers

   • Die App Store Connect-Authentifizierung verwendet kurzlebige JWTs, die aus Ihrem lokalen Systemzeit generiert werden
   • Apple lehnt Token ab, die sich mehr als 20 Minuten in der Zukunft ablaufen, daher kann auch ein kleiner Zeitdrift ein andernfalls gültiges Schlüsselkonto zum Scheitern bringen
   • Auf Windows öffnen Sie Einstellungen > Zeit und Sprache > Datum und Uhrzeit und klicken Sie auf Jetzt synchronisieren
   • Auf macOS öffnen Sie Systemeinstellungen > Allgemein > Datum & Uhrzeit und aktivieren Sie die automatische Uhrzeit
   • Auf Linux überprüfen Sie timedatectl status und aktivieren Sie NTP, wenn erforderlich
   • Nachdem Sie synchronisiert haben, führen Sie den Capgo-Aufbau oder die Capgo-Anmeldekommando erneut aus

   Siehe Apple’s Token für API-Anfragen generieren Dokumentation für die Lebensdauer 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

   • Benötigt 'Entwickler'-Rolle oder höher
   • Überprüfen Sie in App Store Connect -> Benutzer und Zugriff -> Schlüssel

5. Stellen Sie sicher, dass der Schlüssel nicht zurückgezogen ist

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

”Pod install fehlgeschlagen”

Symptome:

• Die Verarbeitung scheitert während der CocoaPods-Installation
• Podfile-Fehler

Lösungen:

1. Überprüfen Sie, ob Podfile.lock im Commit enthalten ist

   git status ios/App/Podfile.lock

2. Testen Sie die Installation von Pods lokal

   cd ios/App
   pod install

3. Nach inkompatiblen Pods suchen

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

4. Pod-Cache löschen

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

Android-Bau-Probleme

”Keystore password incorrect”

Abschnitt mit dem Titel „Falsches Keystore-Passwort“

• Symptome:
• Der Build scheitert während der Signierung

Gradle-Fehler über das Keystore

1. Lösungen:

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

2. In die Zwischenablage kopieren

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

3. Base64-Codierung überprüfen

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

"Kein Alias gefunden"

Symptome:

• Mit Alias-Fehler beim Signieren

Lösungen:

1. Liste der Keystore-Aliasse

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

2. Überprüfen Sie, ob der Alias genau übereinstimmt

   • Der Alias ist case-sensitive
   • Überprüfen Sie in KEYSTORE_KEY_ALIAS nach Tippfehlern

3. Verwenden Sie den richtigen Alias aus dem Keystore

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

”Gradle-Build fehlgeschlagen”

Symptome:

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

Lösungen:

1. Testen Sie lokal erst einmal

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Nach fehlenden Abhängigkeiten suchen

   • build.gradle-Dateien überprüfen
   • Stellen Sie sicher, dass alle Plugins in den Abhängigkeiten aufgeführt sind

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

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

4. Gradle-Cache löschen

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

Play Store-Upload fehlgeschlagen

Symptome:

• Der Build gelingt, aber der Upload schlägt fehl
• Fehler bei der Dienstkontoinstanz

Lösungen:

1. Überprüfe die Dienstkontoinstanz-JSON

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

2. Überprüfe die Berechtigungen der Dienstkontoinstanz

   • Gehe zu Play Console → Setup → API Zugriff
   • Stelle sicher, dass die Dienstkontoinstanz Zugriff auf deine App hat
   • Zulassen Sie die Berechtigung für die „Freigabe in Testspuren“

3. Überprüfen Sie, ob die App in Play Console eingerichtet ist

   • Die App muss vorher in Play Console erstellt werden
   • Zumindest eine APK muss manuell ursprünglich hochgeladen werden

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

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

Allgemeine Probleme

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

Symptome:

• Kann den Build-Status nicht überprüfen
• 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 Antwort der ersten Build-Aktion

3. Überprüfen Sie, ob der Build abgelaufen ist

   • Die Build-Daten sind 24 Stunden verfügbar

”Project sync failed”

Symptome:

• Der Build scheitert, bevor die Kompilierung beginnt
• Fehlende Dateien-Fehler

Lösungen:

1. Führe Capacitor lokal synchron aus

   bunx cap sync

2. Stelle sicher, dass alle native Dateien committet sind

   git status ios/ android/

3. Überprüfe nach git-ignorierten native Dateien

   • Überprüfe .gitignore
   • Stelle sicher, dass wichtige Konfigurationsdateien nicht ignoriert werden

Der Build ist erfolgreich, aber ich sehe keine Ausgabe

Symptome:

• Der Build zeigt Erfolg, aber kein Download-Link

Lösungen:

1. Überprüfe die Build-Konfiguration

   • Die Speicherung von Artefakten mag nicht konfiguriert sein
   • Kontaktiere das Support-Team, wenn der Zugriff auf Artefakte für deinen Build nicht verfügbar ist

2. Für die iOS-Testflug-Submission:

   • Überprüfe App Store Connect
   • Die Verarbeitung kann nach dem Hochladen 5-30 Minuten dauern

3. Für die Android-Play-Store-Submission

   • Überprüfe das Google Play-Console → Testing → Internes Testen
   • Die Verarbeitung kann einige Minuten dauern

CI/CD-Spezifische Probleme

GitHub Aktionen: „Befehl nicht gefunden“

Symptome:

• bunx @capgo/cli@latest … Fehler in CI mit „Befehl nicht gefunden“

Lösungen:

1. Stelle Bun zuerst ein also bunx ist verfügbar:

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

2. Dann führen Sie den CLI aus — bunx es wird es auf Abruf geladen, 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 die Geheimnisse gesetzt sind

   • Zum Repository-Settings → Geheimnisse und Variablen → Aktionen gehen
   • Alle erforderlichen Geheimnisse hinzufügen

2. Verwenden Sie die korrekte Syntax

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

3. Überprüfen Sie, ob die geheimen Namen übereinstimmen

   • Die Namen sind case-sensitive
   • Keine Tippfehler in den geheimen Referenzen

Mehr Hilfe erhalten

Verbose Logging aktivieren

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

Baumaterialien sammeln

Wenn Sie den Support kontaktieren, fügen Sie hinzu:

1. Benutzter Build-Befehl

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

2. Fehlermeldung (vollständiger Output)

3. Job-ID (aus Build-Ausgabe)

4. Build-Protokolle (kopieren Sie den vollständigen Terminal-Ausgang)

5. Umgebungsinformationen

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

Kontakt zum Support

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

Bekannte Einschränkungen

Aktuelle Einschränkungen:

• Maximale Aufbauzeit: 10 Minuten
• Maximale Uploadgröße: ~500 MB
• iOS-Builds erfordern 24-Stunden-Mac-Mietverträge, führen Sie den Aufbau auf einem Mac durch, um die optimale Nutzung sicherzustellen
• Die Verfügbarkeit von Build-Artefakten hängt von der Build-Zielkonfiguration und der Artefakt-Speicherung ab

Diese Einschränkungen können auf der Grundlage von Feedback angepasst werden

Zusätzliche Ressourcen

• Einstieg - Anleitung zur ersten Einrichtung
• iOS-Builds - iOS-spezifische Konfiguration
• Android Builds - Android-spezifische Konfiguration
• CLI Referenz - Vollständige Befehlsdokumentation