Fehlerbehebung

Lösungen für häufige Probleme beim Builden nativer Apps mit Capgo Cloud Build.

Build-Fehler

„Upload fehlgeschlagen“ oder „Verbindungs-Timeout“

Symptome:

• Build schlägt beim Upload des Projekts fehl
• Timeout-Fehler nach 60 Sekunden

Lösungen:

1. Internetverbindung prüfen

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

2. Projektgröße reduzieren

   • Stelle sicher node_modules/ wird nicht hochgeladen (sollte automatisch ausgeschlossen werden)
   • Prüfe auf große Dateien in deinem Projekt:

   find . -type f -size +10M

3. Ablaufdatum der Upload-URL prüfen

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

Tipp

Sehr große Projekte können die Build-Zeit überschreiten (siehe Bekannte Einschränkungen). Wende dich an den Support für Enterprise-Optionen.

„Build-Timeout nach 10 Minuten“

Symptome:

• Build überschreitet die maximal zulässige Zeit
• Status zeigt timeout

Lösungen:

1. Abhängigkeiten optimieren

   • Unbenutzte npm-Pakete entfernen
   • Nutzt npm prune --production vor dem Build

2. Netzwerkprobleme im Build prüfen

   • Einige Abhängigkeiten können während des Builds große Dateien herunterladen
   • Vorab-Caching mit einer Lock-Datei in Betracht ziehen

3. Native Abhängigkeiten prüfen

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

4. Support kontaktieren

   • Falls deine App berechtigterweise mehr Zeit benötigt
   • Wir können Limits für bestimmte Use Cases anpassen

Authentifizierungsprobleme

„API-Key ungültig“ oder „Unauthorized“

Symptome:

• Build schlägt sofort mit Authentifizierungsfehler fehl
• 401- oder 403-Fehler

Lösungen:

1. Prüfen, ob der API-Key korrekt ist

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

2. Berechtigungen des API-Keys prüfen

   • Der Key muss über write oder all Berechtigungen
   • Im Capgo-Dashboard unter API Keys prüfen

3. Stellen Sie sicher, dass der API-Key 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-spezifischer Fehler

Lösungen:

1. Prüfen, ob die App registriert ist

   bunx @capgo/cli@latest app list

2. App-ID-Übereinstimmung prüfen

   • Prüfen capacitor.config.json appId
   • Ensure command uses correct app ID

3. Organisationszugriff prüfen

   • Prüfen, ob Sie sich in der richtigen Organisation befinden
   • Der API-Key muss Zugriff auf die Organisation der App haben

iOS-Build-Probleme

„Code-Signing fehlgeschlagen“

Symptome:

• Build schlägt in der code-Signierphase fehl
• Xcode-Fehler zu Zertifikaten oder Profilen

Lösungen:

1. Zertifikatstyp muss zum Build-Typ passen

   • Entwicklungs-Builds benötigen Entwicklungszertifikate
   • App-Store-Builds benötigen Distribution-Zertifikate

2. Zertifikat und Profil müssen ü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. Provisioning-Profil muss gültig sein

   • Ablaufdatum prüfen
   • App-ID muss enthalten sein
   • Prüfen, ob das Zertifikat enthalten ist

4. Zugangsdaten neu generieren

   • Altes Zertifikat/Profil löschen
   • Neue im Apple Developer Portal erstellen
   • Neu kodieren und Umgebungsvariablen aktualisieren

„Provisioning Profile enthält kein Signing-Zertifikat“

Symptome:

• Xcode kann das Zertifikat im Profil nicht finden

Lösungen:

1. Neuestes Profil von Apple herunterladen

   • Gehe zu Apple Developer → Zertifikate, IDs & Profile
   • Provisionierungsprofil herunterladen
   • Ensure it includes your certificate

2. Zertifikat im Profil prüfen

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

3. Profil mit dem richtigen Zertifikat neu erstellen

   • Profil im Apple-Developer-Portal bearbeiten
   • Stellen Sie sicher, dass Ihr Distribution-Zertifikat ausgewählt ist
   • Herunterladen und neu kodieren

„Authentifizierung bei App Store Connect fehlgeschlagen“

Symptome:

• TestFlight-Upload schlägt fehl
• API Key-Fehler

Lösungen:

1. Zugangsdaten für API Key prüfen

   • APPLE_KEY_ID prüfen (sollte 10 Zeichen lang sein)
   • APPLE_ISSUER_ID prüfen (sollte UUID-Format haben)
   • Prüfen, ob APPLE_KEY_CONTENT korrekt base64-kodiert ist

2. Systemuhr synchronisieren

   • Die Authentifizierung bei App Store Connect nutzt kurzlebige JWTs, die aus deiner lokalen Systemzeit generiert werden.
   • Apple lehnt Tokens ab, die mehr als 20 Minuten in der Zukunft ablaufen; selbst kleine Uhrzeitabweichungen können einen ansonsten gültigen Key scheitern lassen.
   • Unter Windows öffnen: Einstellungen > Zeit & Sprache > Datum & Uhrzeit und klicke auf Sync now
   • Öffnen Sie auf macOS Systemeinstellungen > Allgemein > Datum & Uhrzeit und aktivieren Sie die automatische Uhrzeit
   • Prüfen Sie auf Linux timedatectl status und aktivieren Sie NTP bei Bedarf
   • Führen Sie nach der Synchronisierung den Capgo-Build- oder Credential-Befehl erneut aus

   Siehe Apples Token-Erstellung für API-Anfragen Dokumentation zur Gültigkeitsdauer von App Store Connect-Tokens.

3. API-Schlüssel lokal testen

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

4. Berechtigungen des API-Schlüssels prüfen

   • Schlüssel benötigt die Rolle „Developer“ oder höher
   • In App Store Connect -> Benutzer und Zugriff -> Schlüssel überprüfen

5. Stellen Sie sicher, dass der Key nicht widerrufen wurde

   • In App Store Connect prüfen
   • Bei Bedarf neuen Schlüssel generieren

App stürzt beim Start auf iOS 27 ab

Symptome:

• Die mit Xcode 27 gebaute App schließt sich sofort auf iOS 27 (TestFlight oder Gerät)
• Der Crash-Report zeigt _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Lösung: Apps, die mit iOS 27 SDK gebaut werden, müssen den UIScene-Lebenszyklus übernehmen. Füge hinzu SceneDelegate und einen UIApplicationSceneManifest zu ios/App/App/Info.plist, oder baue mit --xcode-version 26. Capgo blockiert diese Builds nun, bevor sie starten (Prescan-Check ios/plist-scene-lifecycle-xcode27).

„Pod install fehlgeschlagen“

Achtung

Capgo Build stellt im Dezember 2026 das Bauen von CocoaPods-Projekten ein. Migration zu Swift Package Manager: siehe Capacitor SPM-Guide.

Symptome:

• Build schlägt während der CocoaPods-Installation fehl
• Podfile-Fehler

Lösungen:

1. Prüfen, ob Podfile.lock committet ist

   git status ios/App/Podfile.lock

2. pod install lokal testen

   cd ios/App
   pod install

3. Auf inkompatible Pods prüfen

   • Podfile auf Versionskonflikte prüfen
   • Stelle sicher, dass alle Pods dein iOS Deployment Target unterstützen

4. Pod-Cache leeren

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

Android-Build-Probleme

„Keystore-Passwort falsch“

Symptome:

• Build schlägt beim Signing fehl
• Gradle-Fehler zum Keystore

Lösungen:

1. Keystore-Passwort prüfen

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

2. Umgebungsvariablen checken

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

3. Base64-Kodierung prüfen

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

„Key alias not found“

Symptome:

• Signing schlägt mit Alias-Fehler fehl

Lösungen:

1. Keystore-Aliase auflisten

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

2. Prüfen, ob der Alias exakt übereinstimmt

   • Alias ist case-sensitive
   • Tippfehler in KEYSTORE_KEY_ALIAS prüfen

3. Korrekten Alias aus dem Keystore verwenden

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

„Gradle build failed“

Symptome:

• Allgemeine Gradle-Fehler
• Kompilierungs- oder Dependency-Probleme

Lösungen:

1. Build zuerst lokal testen

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Fehlende Dependencies prüfen

   • build.gradle-Dateien prüfen
   • Sicherstellen, dass alle Plugins in den dependencies stehen

3. Gradle-Versionskompatibilität prüfen

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

4. Gradle-Cache leeren

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

„Play Store upload failed“

Symptome:

• Build erfolgreich, aber Upload schlägt fehl
• Service-Account-Fehler

Lösungen:

1. Service-Account-JSON prüfen

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

2. Berechtigungen des Service-Accounts prüfen

   • Play Console → Setup → API Access
   • Sicherstellen, dass der Service-Account Zugriff auf deine App hat
   • Berechtigung „Release to testing tracks“ erteilen

3. Prüfen, ob die App im Play Console eingerichtet ist

   • Die App muss zuerst in der Play Console erstellt werden
   • Zunächst muss mindestens eine APK manuell hochgeladen werden

4. Prüfen, ob API aktiviert ist

   • Google Play Developer API muss aktiviert sein
   • In der Google Cloud Console prüfen

Allgemeine Probleme

„Job not found“ oder „Build status unavailable“

Symptome:

• Build-Status kann nicht abgerufen werden
• Fehler bei der Job-ID

Lösungen:

1. Warte kurz und versuche es erneut

   • Build-Jobs können einige Sekunden zur Initialisierung benötigen

2. Prüfe, ob die Job-ID korrekt ist

   • Job-ID aus der ersten Build-Response prüfen

3. Prüfen, ob der Build abgelaufen ist

   • Build-Daten sind 24 Stunden verfügbar

„Project sync failed“

Symptome:

• Build schlägt vor der Kompilierung fehl
• Fehler durch fehlende Dateien

Lösungen:

1. Capacitor sync lokal ausführen

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Prüfen Sie auf gitignorierte native Dateien

   • .gitignore überprüfen
   • Wichtige Config-Dateien nicht ignorieren

„Build erfolgreich, aber ich sehe keinen Output“

Symptome:

• Build zeigt Erfolg an, aber kein Download-Link

Lösungen:

1. Build-Konfiguration prüfen

   • Artifact storage may not be configured
   • Kontaktiere den Support, wenn der Artefakt-Zugriff für deinen Build nicht verfügbar ist

2. Für die iOS-TestFlight-Einreichung

   • App Store Connect prüfen
   • Die Verarbeitung kann nach dem Upload 5–30 Minuten dauern

3. Für den Android Play Store

   • Play Console → Testing → Internal testing prüfen
   • Die Verarbeitung kann einige Minuten dauern

Build erfolgreich, aber falsches Artefakt nach Environment-Wechsel

Symptome:

• Build-Status ist success aber die IPA/AAB/APK passt nicht zum gerade gebauten Branch oder Flavor
• Android AAB fehlt oder ist falsch nach dem Wechsel zwischen RC- und Production-Credentials oder --android-flavor
• Build ist verdächtig schnell fertig, direkt nach Änderung der Signing Config oder des Product Flavors

Ursache: Capgo stellt standardmäßig den Build-Cache pro App wieder her standardmäßig (weglassen cache_key den gemeinsamen General Cache weg). Wenn RC und Production dieselbe App ID ohne separate Keys nutzen, kann ein Restore den kompilierten Output der vorherigen Umgebung wiederverwenden.

Lösungen:

1. Nutzen Sie einen Cache-Key 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. Erzwinge einen sauberen Build beim Debugging:

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

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

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

CI/CD-spezifische Probleme

GitHub Actions: „Command not found“

Symptome:

• bunx @capgo/cli@latest … schlägt in CI mit „command not found“ fehl

Lösungen:

1. Bun zuerst einrichten damit bunx verfügbar ist:

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

2. Dann führe CLI aus — bunx ruft es bei Bedarf ab, keine globale Installation nötig:

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

GitHub Actions: „Secrets not found“

Symptome:

• Umgebungsvariablen im Build leer

Lösungen:

1. Prüfe, ob Secrets gesetzt sind

   • Gehe zu Repo-Einstellungen → Secrets and variables → Actions
   • Füge alle erforderlichen Secrets hinzu

2. Verwende die korrekte Syntax

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

3. Secret-Namen abgleichen

   • Namen sind case-sensitive
   • Keine Tippfehler in Secret-Referenzen

Weitere Hilfe

Verbose Logging aktivieren

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

Build-Informationen sammeln

When contacting support, include:

1. Verwendeter Build-Befehl

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

2. Fehlermeldung (vollständige Ausgabe)

3. Job-ID (aus der Build-Ausgabe)

4. Build-Logs (komplette Terminalausgabe kopieren)

5. Umgebungsinformationen

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

Support kontaktieren

• Discord: Tritt unserer Community bei
• E-Mail: support@capgo.app
• Dokumentation: Capgo Doku

Bekannte Einschränkungen

Aktuelle Einschränkungen:

• Maximale Build-Zeit: 10 Minuten
• Maximale Upload-Größe: ~500 MB
• iOS-Builds erfordern 24-Stunden-Mac-Leases; Builds auf dem Mac werden eingereiht, um eine optimale Auslastung zu gewährleisten
• Die Verfügbarkeit des Build-Artifact-Downloads hängt vom Build-Ziel und der Artifact-Storage-Konfiguration ab

Diese Limits können basierend auf Feedback angepasst werden.

Prescan hat meinen Build blockiert

Capgo führt einen lokalen Prescan vor dem Upload aus. Behebe den gemeldeten Befund oder ignoriere nur diese Check-ID:

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

Den vollständigen Katalog ansehen: Prescan-Checks.

Weitere Ressourcen

• Erste Schritte - Einrichtungsanleitung
• Konfigurationsoptionen - CLI-Flags, einschließlich --cache-key und --no-cache
• iOS-Builds - iOS-spezifische Konfiguration
• Android-Builds - Android-spezifische Konfiguration
• Prescan-Checks - Vollständige Liste der Pre-Build-Checks und Ignore-Flags
• CLI Referenz - Vollständige Befehlsdokumentation