Problembehandlung

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

Build-Fehler

”Upload failed” or “Connection timeout”

Abschnitt mit dem Titel “” ,

• oder „Verbindungstimeout“”
• Symptome:

Der Build scheitert während der Projekt-Upload

1. Timeout-Fehler nach 60 Sekundenen

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

2. Projektgröße reduzieren

   • Sicherstellen 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 verfallen nach 1 Stunde
   • Wenn Sie ein Ablaufdatum-URL-Fehler erhalten, führen Sie den Befehl zum Neubauen erneut aus

Tip

Große Projekte können die Build-Zeitgrenze erreichen (siehe Known LimitationsKontaktiere den Support für Unternehmensoptionen.

”Build timeout nach 10 Minuten”

Symptome:

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

Lösungen:

1. Optimiere Abhängigkeiten

   • Entferne 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 die 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 die Grenzen für bestimmte Anwendungsfälle anpassen

Authentifizierungsprobleme

“API Schlüssel ungültig” oder „Keine Berechtigung“

Symptome:

• Der Build scheitert sofort mit einem 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 der Capgo-Oberfläche 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. Neu authentifizieren

   bunx @capgo/cli@latest login

„Anwendung nicht gefunden“ oder „Keine Berechtigung für diese Anwendung“

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 capacitor.config.json appId
   • Stellen Sie sicher, dass die Kommandozeile den richtigen App-ID verwendet

3. Überprüfen Sie die Zugriffsberechtigungen der Organisation

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

iOS Build Probleme

„Code Signierung fehlgeschlagen“

Symptome:

• Die code Signierung schlägt während des Build-Prozesses fehl
• Xcode meldet Fehler bei Zertifikaten oder Profilen

Lösungen:

1. Überprüfen Sie, ob das Zertifikattyp mit dem Buildtyp übereinstimmt

   • Entwicklungsbuilds benötigen Entwicklungszertifikate
   • App Store Builds 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 Bereitstellungsprofilvalid ist

   • Ü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 im Apple-Entwickler-Portal
   • Re-encode und aktualisieren Sie die Umgebungsvariablen

„Provisioning-Profil enthält kein Signierungszertifikat“

Symptome:

• Xcode kann kein Zertifikat in Profil finden

Lösungen:

1. Neuestes Profil von Apple herunterladen

   • Zum Apple Developer → Zertifikate, IDs und Profile gehen
   • Provisioning-Profil herunterladen
   • 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. Neues Profil mit korrektem Zertifikat erstellen

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

”Authentifizierung bei App Store Connect fehlgeschlagen”

Symptome:

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

Lösungen:

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

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

2. Synchronisiere den Uhrzeigerschlag deines Computers

   • Die App Store Connect-Authentifizierung verwendet kurzlebige JWTs, die aus deinem lokalen Systemzeit generiert werden
   • Apple lehnt Token ab, die sich mehr als 20 Minuten in der Zukunft ablaufen, sodass sogar kleine Uhrschwünge einen sonst gültigen Schlüssel zum Scheitern bringen können
   • Auf Windows öffne Einstellungen > Zeit und Sprache > Datum und Uhrzeit und klicke Jetzt synchronisieren
   • Auf macOS öffne Systemeinstellungen > Allgemein > Datum und Uhrzeit und aktiviere die automatische Uhrzeit
   • Auf Linux überprüfe timedatectl status und aktiviere NTP, wenn erforderlich
   • After dem Synchronisieren, den Capgo Build oder Zugriffsbefehl nochmals ausführen

   Siehe Apples Token generieren für API Anforderungen Dokumentation für die App Store Connect Token Lebensdauer Regel

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 den 'Entwickler'-Rollen 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
   • Neue Schlüssel generieren, wenn erforderlich

„Pod-Installierung fehlgeschlagen“

Symptome:

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

Lösungen:

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

   git status ios/App/Podfile.lock

2. Testen Sie die lokale Pod-Installierung

   cd ios/App
   pod install

3. Nach inkompatiblen Pods suchen

   • Überprüfe Podfile auf Versionskonflikte
   • Stelle 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-Bauprobleme

„Falsches Keystore-Passwort“

Symptome:

• Build fehlschlägt während der Signierung
• Gradle-Fehler über das Keystore

Lösungen:

1. Überprüfe das Keystore-Passwort

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

2. Überprüfe die Umgebungsvariablen

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

3. Überprüfe die Base64-Codierung

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

Alias nicht gefunden

Symptome:

• Signieren fehlschlägt aufgrund Alias-Fehler

Lösungen:

1. Liste der Schlüsselkasten-Aliase

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

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

   • Der Alias ist case-sensitive
   • Überprüfe auf Tippfehler in KEYSTORE_KEY_ALIAS

3. Verwende den richtigen Alias aus dem Schlüsselkasten

   # 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 den lokalen Build 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 scheitert
• Dienstkontoe Fehler

Lösungen:

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

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

2. Überprüfen Sie die Dienstkontoe-Rechte

   • Gehe zu Play Console → Setup → API Zugriff
   • Stellen Sie sicher, dass das Dienstkonto Zugriff auf Ihre App hat
   • Erlauben Sie die Berechtigung „Freigabe in Testtracks“

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

   • Die App muss in Play Console erstellt werden
   • Zumindest ein 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 im Google Cloud Console

Allgemeine Probleme

”Job not found” or “Build status unavailable”

Abschnitt mit dem Titel „ , „Job nicht gefunden“ oder „Build-Status nicht verfügbar““

• Symptome:
• Der Build-Status kann nicht überprüft werden

Fehler bei der Job-ID

1. Lösungen: Überprüfen Sie, ob __CAPGO_KEEP_0__ aktiviert ist

   • Die Initialisierung von Build-Aufträgen kann einige Sekunden dauern

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

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

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

   • Die Build-Daten sind 24 Stunden verfügbar

Projekt-Synchronisierung fehlgeschlagen

Symptome:

• Der Build scheitert, bevor die Kompilierung beginnt
• Fehlende Dateien fehlerhaft

Lösungen:

1. Capacitor synchronisieren Sie lokal

   bunx cap sync

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

   git status ios/ android/

3. Überprüfen Sie native Dateien, die in .gitignore gelistet sind

   • Ü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

   • Die Speicherung von Artefakten kann nicht konfiguriert sein
   • Wenden Sie sich an den Support, wenn der Zugriff auf Artefakte für Ihre Build nicht verfügbar ist

2. Für die iOS-Testflug-Submission

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

3. Für die Android-Play-Store-Veröffentlichung

   • Überprüfen Sie 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 … 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 Anforderung, 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 die Geheimnisse gesetzt sind

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

2. Verwenden Sie die richtige Syntax

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

3. Überprüfen Sie, ob die Geheimnisnamen übereinstimmen

   • Die Namen sind case-sensitive
   • No Tippfehler in geheimen Referenzen

Erhalten Sie mehr Hilfe

Verbose Logging aktivieren

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

Baumeldinformationen sammeln

Bei der Kontaktaufnahme mit dem Support einschließen:

1. Verwendeter Build-Befehl

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

2. Fehlermeldung (voller Ausgabe)

3. Auftrag ID (aus der Ausgabe der Build-Phase)

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

5. Umgebungsinformationen

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

Kontaktieren Sie den Support

• Discord: Bereinigen Sie unsere Gemeinschaft
• Email: support@capgo.app
• Dokumentation: Capgo Dokumentation

Bekannte Einschränkungen

Derzeitige Einschränkungen:

• Höchstzeit für die Erstellung: 10 Minuten
• Höchstuploadgröße: ~500 MB
• iOS-Builds erfordern 24-Stunden-Mac-Mietverträge, führen Sie die Erstellung auf einem Mac durch, um die optimale Nutzung sicherzustellen
• Die Verfügbarkeit von Build-Artifacts hängt von der Zielkonfiguration und der Speicherung der Artefakte ab.

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

Zusätzliche Ressourcen

• Anfangen - Anleitung zur ersten Einrichtung
• iOS-Builds - iOS-spezifische Konfiguration
• Android-Builds - Android-spezifische Konfiguration
• CLI-Referenz - Vollständige Dokumentation der Befehle