Fehlerbehebung

Lösungen für häufige Probleme beim Erstellen von nativen Apps mit Capgo Cloud Build.

Build-Fehler

”Upload failed” or “Connection timeout”

oder

• Verbindungstimeout
• Sektion:

Upload fehlgeschlagen

1. oder

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

2. Projektgröße reduzieren

   • Stellen Sie sicher 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 gelten nur eine Stunde
   • Wenn Sie eine abgelaufene URL-Fehlermeldung erhalten, führen Sie den Build-Befehl erneut aus

Tipp

Sehr große Projekte können die Build-Zeitgrenze erreichen (siehe Bekannte Einschränkungen. Kontaktiere den Support für Unternehmensoptionen.

„Build-Timeout nach 10 Minuten“

Symptome:

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

Lösungen:

1. Optimiere Abhängigkeiten

   • Entferne nicht benötigte npm-Pakete
   • Verwende npm prune --production vor dem Build

2. Überprüfen Sie Netzwerkprobleme im Build

   • Einige Abhängigkeiten laden während des Builds große Dateien herunter
   • Überlegen Sie sich, vorab zu cachieren 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 die Grenzen für bestimmte Anwendungsfälle anpassen

Authentifizierungsprobleme

API-Schlüssel ungültig

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 für den API-Schlüssel

   • Der Schlüssel muss write oder all Berechtigungen
   • Ü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. Wieder authentifizieren

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

Abschnitt mit dem Titel ,

• Symptome:

Die Authentifizierung funktioniert, aber es tritt ein App-spezifisches Fehler auf

1. App registrieren Sie bestätigen

   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 die richtige App-ID verwendet

3. Überprüfen Sie die Zugriffsberechtigung

   • Überprüfen Sie, ob Sie sich im richtigen Unternehmen befinden
   • API muss Zugriff auf die Organisation der App haben

iOS-Bau-Probleme

”Code Signvorgang fehlgeschlagen”

Symptome:

• Der Aufbau scheitert während des code Signvorgangs
• Xcode-Fehler über Zertifikate oder Profile

Lösungen:

1. Überprüfen Sie, ob der Zertifikat-Typ mit dem Aufbau-Typ übereinstimmt

   • Entwicklungs-Aufbauten benötigen Entwicklungszertifikate
   • App-Store-Aufbauten benötigen Verteilungszertifikate

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 die Bereitstellungsvorlage gültig ist

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

4. Regenerieren Sie die Anmeldeinformationen

   • Löschen Sie das alte Zertifikat/Vorlage
   • Erstellen Sie neue in Apple Developer-Portal
   • Wieder-encode und aktualisieren Sie die Umgebungsvariablen

“Die Bereitstellungsvorlage enthält kein Signierungszertifikat”

Symptome:

• Xcode kann das Zertifikat in der Vorlage nicht finden

Lösungen:

1. Downloaden Sie das aktuellste Profil von Apple

   • Zum Apple Developer-Portal gehen → Zertifikate, IDs und Profile
   • Provisioning-Profil herunterladen
   • Stellen Sie sicher, dass es Ihr Zertifikat enthält

2. Zertifikat im Profil überprüfen

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

3. Neues Profil mit korrektem Zertifikat erstellen

   • Im Apple Developer-Portal das Profil bearbeiten
   • Stellen Sie sicher, dass Ihr Verteilungs-Zertifikat ausgewählt ist
   • Herunterladen und erneut kodieren

”App Store Connect-Authentifizierung fehlgeschlagen”

Symptome:

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

Lösungen:

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

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

2. Synchronisieren Sie die Uhr Ihres Computers

   • App Store Connect-Authentifizierung verwendet JWTs mit kurzer Gültigkeit, die aus Ihrem lokalen Systemzeit generiert werden
   • Apple lehnt Token ab, die mehr als 20 Minuten in der Zukunft ablaufen, daher kann auch ein kleiner Zeitdrift ein andernfalls gültiges Schlüssel abgelehnt werden
   • Auf Windows öffnen Sie Einstellungen > Zeit und Sprache > Datum und Uhrzeit und klicken Sie auf Jetzt synchronisieren
   • 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
   • Nach der Synchronisierung führen Sie den Capgo-Aufbau oder die Anmeldekommando erneut aus

   Siehe Apple’s Token generieren für API Anfragen Dokumentation für die App Store Connect Token-Laufzeitregel

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 API-Schlüsselberechtigungen

   • Der Schlüssel benötigt die Rolle „Entwickler“ oder eine höhere
   • Überprüfen Sie in App Store Connect -> Benutzer und Zugriff -> Schlüssel

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

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

„Pod install fehlgeschlagen“

Symptome:

• Die Build-Funktion fehlt während der CocoaPods-Installation
• Fehler im Podfile

Lösungen:

1. Überprüfen Sie, ob Podfile.lock im Repository committet wurde

   git status ios/App/Podfile.lock

2. Testen Sie die lokale Pod-Installation

   cd ios/App
   pod install

3. Überprüfen Sie, ob inkompatible Pods installiert sind

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

4. Löschen Sie den Pod-Cache

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

Android-Bauprobleme

„Falscher Keystore-Passwort“

Symptome:

• Der Build scheitert während der Signierung
• Gradle-Fehler über den 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

Schlüsselalias nicht gefunden

Symptome:

• Das Signieren scheitert mit Alias-Fehler

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üfe die Tippfehler in KEYSTORE_KEY_ALIAS

3. Verwende 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
• Komplettions- oder Abhängigkeitsprobleme

Lösungen:

1. Testen Sie die lokale Build-Installation zuerst

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Überprüfen Sie fehlende Abhängigkeiten

   • Überprüfen Sie die Dateien build.gradle
   • 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

Fehler beim Hochladen in die Play Store

Symptome:

• Der Build gelingt, aber das Hochladen schlägt fehl
• Fehler bei der Dienstkonten-Konfiguration

Lösungen:

1. Dienstkontoinformationen als JSON überprüfen

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

2. Dienstkontoinstallationsrechte überprüfen

   • Zu Google Play Console → Setup → API Zugriff gehen
   • Stellen Sie sicher, dass der Dienstkontoinhaber Zugriff auf Ihre App hat
   • Berechtigung „Release to testing tracks“ erteilen

3. Stellen Sie sicher, dass die App in Google Play Console eingerichtet ist

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

4. Stellen Sie sicher, dass API aktiviert ist

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

Allgemeine Probleme

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

Häufige Symptome:

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

Lösungen:

1. Warten Sie einen Moment und versuchen Sie es erneut

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

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

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

3. Überprüfen Sie, ob die Build-Auftragsfrist abgelaufen ist

   • Die Build-Daten sind 24 Stunden verfügbar

Projekt-Synchronisierung fehlgeschlagen

Symptome:

• Die Build-Ausführung scheitert vor der Kompilationsphase
• Fehlende Dateien fehlerhaft

Lösungen:

1. Capacitor lokal synchronisieren

   bunx cap sync

2. Stellen Sie sicher, dass alle native Dateien committiert sind

   git status ios/ android/

3. Überprüfen Sie native Dateien, die von Git ignoriert werden

   • Überprüfen Sie .gitignore
   • Stellen Sie sicher, dass wichtige Konfigurationsdateien nicht ignoriert werden

"Der Build war erfolgreich, aber ich sehe keine Ausgabe"

Symptome:

• Der Build zeigt Erfolg, aber kein Downloadlink

Lösungen:

1. Überprüfen Sie die Build-Konfiguration

   • Kann die Artefakt-Speicherung nicht konfiguriert sein
   • Kontaktiere den Support, wenn der Zugriff auf Artefakte für deine Build nicht verfügbar ist

2. Für die iOS-Testflug-Übermittlung

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

3. Für den Android Play Store

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

Der Build war erfolgreich, aber das Artefakt ist falsch nach einer Umgebungsänderung

Symptome:

• Der Build-Status ist success Aber die IPA/AAB/APK passt nicht zur gerade erstellten Branch oder Flavor
• Android AAB fehlt oder ist falsch nach Wechsel von RC vs Produktionsanmeldeinformationen oder --android-flavor
• Die Erstellung endet verdächtig schnell, nachdem Sie die Signierungs-Konfiguration oder das Produktflavor geändert haben

Ursache: Capgo stellt die pro-Anwendung-Cache wieder her standardmäßig (auslassen cache_key für den gemeinsamen allgemeinen Cache). Wenn RC und Produktionsumgebung denselben App-Id ohne separate Schlüssel teilen, kann eine Wiederherstellung den vorherigen Umgebung kompilierte Ausgabe verwenden.

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. Einen sauberen Build durchführen während Sie debuggen:

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

3. In API oder Webhook-Integrationen, passieren cache_key zum Beispiel "prod") oder setzen cache_enabled: false für einen einzelnen sauberen Lauf.

Siehe Build-Cache für die vollständige Optionenreferenz.

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 vorher ein dann bunx ist verfügbar:

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

2. Dann führen Sie dann den CLI aus — bunx es wird auf Anforderung 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 sind in der Build leer

Lösungen:

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

   • Gehe zu Repository-Einstellungen → Geheimdaten und Variablen → Aktionen
   • Fügen Sie alle erforderlichen Geheimdaten hinzu

2. Verwenden Sie die richtige Syntax

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

3. Überprüfen Sie, ob die Geheimnisschlüssel übereinstimmen

   • Die Namen sind case-sensitive
   • Keine Tippfehler in den Geheimnisschlüsselverweisen

Mehr Hilfe erhalten

Verbose Logging aktivieren

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

Baumeldinformationen sammeln

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

1. Benutzter Build-Befehl

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

2. Fehlermeldung (vollständiger Ausgabe)

3. Job-ID (aus der Ausgabemeldung)

4. Build-Protokolle (kopieren Sie die vollständige Terminal-Ausgabe)

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

Derzeitige Einschränkungen:

• Maximale Bauzeit: 10 Minuten
• Maximale Uploadgröße: ~500 MB
• iOS-Builds erfordern 24-Stunden-Mac-Mietverträge, der Build auf einem Mac wird in die Warteschlange eingereiht, um eine optimale Nutzung sicherzustellen
• Die Verfügbarkeit von Build-Artikeln zum Herunterladen hängt von der Build-Zielkonfiguration und der Konfiguration der Artefakt-Speicherung ab

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

Prescan hat meinen Build blockiert

Capgo führt ein lokales Prüfung vor dem Upload durch. Beheben Sie das gemeldete Problem oder ignorieren Sie nur diese Prüfungs-ID:

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

Siehe das vollständige Katalog: Prescan-Überprüfungen.

Zusätzliche Ressourcen

• Einstieg - Anleitung zur ersten Einrichtung
• Konfigurationsmöglichkeiten - CLI Flags einschließlich --cache-key und --no-cache
• iOS-Builds - iOS-spezifische Konfiguration
• Android-Builds - Androidspezifische Konfiguration
• Prescan-Überprüfungen - Vollständige Liste der Vorbereitungsprüfungen und Ignorierflagge
• CLI Referenz - Vollständige Dokumentation der Befehle