Fehlersuche

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

Build-Fehler

“Hochladen fehlgeschlagen” oder “Verbindungstimeout”

Symptome:

• Build fehlschlägt während des Projektuploads
• __CAPGO_KEEP_0__

Lösungen:

1. Überprüfen Sie Ihre Internetverbindung

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

2. Projektrückstand reduzieren

   • Stellen Sie sicher node_modules/ __CAPGO_KEEP_0__ (sollte automatisch ausgeschlossen werden)
   • Überprüfen Sie Ihren Projekt nach großen Dateien:

   find . -type f -size +10M

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

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

Tipp

Große Projekte können die Build-Zeitgrenze erreichen (siehe Bekannte EinschränkungenKontaktieren Sie den Support für Unternehmensoptionen.

Build-Zeitüberschreitung nach 10 Minuten

Symptome:

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

Lösungen:

1. Abhängigkeiten optimieren

   • Überflüssige npm-Pakete entfernen
   • Verwenden Sie npm prune --production vor dem Bauen

2. Überprüfen Sie Netzwerkprobleme beim Bauen

   • Einige Abhängigkeiten laden während des Baus große Dateien herunter
   • Überlegen Sie sich, Vorkacheln mit einem Lock-File zu verwenden

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

   • If your app genuinely needs more time
   • 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 für die API-Schlüssel

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

App nicht gefunden

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

3. Organisationszugriff überprüfen

   • Stellen Sie sicher, dass Sie sich in der richtigen Organisation befinden
   • API Schlüssel muss Zugriff auf die Organisation des Apps haben

iOS-Bauprobleme

„Code Signieren fehlgeschlagen“

Symptome:

• Der Aufbau scheitert während der code-Signierungsphase
• Xcode-Fehler zu Zertifikaten oder Profilen

Lösungen:

1. Stellen Sie sicher, dass der Zertifikentyp dem Build-Typ entspricht

   • Entwicklungsbuilds benötigen Entwicklerzertifikate
   • 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 Provisioning-Profile gültig sind

   • Überprüfen Sie die Ablaufzeit
   • Stellen Sie sicher, dass 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/Profild
   • Erstellen Sie neue im Apple-Entwicklerportal
   • Umweltvariablen neu kodieren und aktualisieren

”Provisioning profile doesn’t include signing certificate”

Symptome:

• Xcode kann das Zertifikat im Profil nicht finden

Lösungen:

1. Neuestes Profil von Apple herunterladen

   • Zu 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. Profil mit korrektem Zertifikat erneut erstellen

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

”App Store Connect authentication failed”

Symptome:

• Hochladen auf TestFlight fehlt
• 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 im UUID-Format sein)
   • Überprüfen Sie, ob APPLE_KEY_CONTENT korrekt base64-codiert ist

2. Testen Sie API-Schlüssel lokal

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

3. Überprüfen Sie API-Schlüssel-Rechte

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

4. 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 Build-Funktion fehlschlägt während der CocoaPods-Installation
• Fehler im Podfile

Lösungen:

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

   git status ios/App/Podfile.lock

2. Teste die lokale Pod-Install-Installation

   cd ios/App
   pod install

3. Überprüfen Sie inkompatible Pods

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

4. Leeren Sie den Pod-Cache

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

Android-Bauprobleme

„Falsches Keystore-Passwort“

Symptome:

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

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

3. Überprüfe Base64-Codierung

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

„Alias für Schlüssel nicht gefunden“

Symptome:

• Das Signieren fehlt 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 failed”

Abschnitt mit dem Titel „ , Gradle-Build fehlgeschlagen““

• Symptome:
• Allgemeine Gradle-Fehler

Fehler bei der Kompilierung oder den Abhängigkeiten

1. Lösungen:

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Zur Zwischenablage kopieren

   • Überprüfen Sie fehlende Abhängigkeiten
   • 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 fehlschlägt
• Fehler bei der Dienstkontoinstanz

Lösungen:

1. Dienstkonten JSON-Datei überprüfen

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

2. Dienstkontenrechte überprüfen

   • Zum Play-Console → Einstellungen → API Zugriff gehen
   • Stellen Sie sicher, dass die Dienstkonten Zugriff auf Ihre App haben
   • Berechtigung „Release to testing tracks“ erteilen

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

   • Die App muss im Play-Console erstellt werden
   • Zumindest eine APK muss manuell hochgeladen werden

4. Stellen Sie sicher, dass 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 beim 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 die Job-ID auf Richtigkeit

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

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

   • Die Build-Daten sind für 24 Stunden verfügbar

”Project sync failed”

Symptome:

• Die Build-Aktion scheitert, bevor die Kompilierung beginnt
• Fehler bei fehlenden Dateien

Lösungen:

1. Führen Sie Capacitor lokal synchron durch

   bunx cap sync

2. Stellen Sie sicher, dass alle native Dateien committet 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

”Build succeeded but I don’t see output”

,

• ,

,

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-Submission

   • Ü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 … fehlt in CI mit “Befehl nicht gefunden”

Lösungen:

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

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

2. Dann CLI ausführen — 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
   • Keine Tippfehler in den Geheimnisreferenzen

Mehr Unterstützung erhalten

Ausführliche Protokollierung aktivieren

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

Baumodusinformationen sammeln

Bei der Kontaktaufnahme mit dem Support mitteilen:

1. Verwendeter Befehl zum Bauen

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

2. Fehlermeldung (vollständiger Ausgabe)

3. Auftrags-ID (aus Ausgabemeldung)

4. Aufbauprotokolle (Kopieren Sie die vollständige Terminalausgabe)

5. Umgebungsinformationen

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

Kontakt zu Support

• Discord: Beteiligen Sie sich an unserer Community
• 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 optimalen Verwendungen sicherzustellen
• Die Verfügbarkeit von Build-Artefakten zum Herunterladen hängt von der Zielkonfiguration des Aufbaus und der Konfiguration 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 Dokumentation der Befehle