Troubleshooting

Solutions aux problèmes courants lors de la compilation d'apps natives avec Capgo Cloud Build.

Échecs de build

« Échec de l'upload » ou « Délai de connexion dépassé »

Symptômes :

• Le build échoue lors de l'upload du projet
• Erreurs de timeout après 60 secondes

Solutions :

1. Vérifiez votre connexion internet

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

2. Réduisez la taille du projet

   • Assurez-vous node_modules/ n'est pas en cours d'upload (devrait être exclu automatiquement)
   • Check for large files in your project:

   find . -type f -size +10M

3. Vérifier l'expiration de l'URL d'upload

   • Les URL d'upload expirent après 1 heure
   • Si vous recevez une erreur d'URL expirée, relancez la commande de build

Astuce

Les projets très volumineux peuvent atteindre la limite de temps de build (voir Limitations connues). Contactez le support pour les options entreprise.

« Délai de build dépassé après 10 minutes »

Symptômes :

• Le build dépasse la durée maximale autorisée
• Le statut indique timeout

Solutions :

1. Optimiser les dépendances

   • Supprimer les packages npm inutilisés
   • Utiliser npm prune --production avant le build

2. Vérifier les problèmes réseau pendant le build

   • Certaines dépendances peuvent télécharger des fichiers volumineux pendant le build
   • Envisagez le pré-caching avec un fichier lock

3. Vérifier les dépendances natives

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

4. Contacter le support

   • Si votre application a réellement besoin de plus de temps
   • We can adjust limits for specific use cases

Problèmes d'authentification

« API key invalid » ou « Unauthorized »

Symptômes :

• Le build échoue immédiatement avec une erreur d'authentification
• Erreurs 401 ou 403

Solutions :

1. Vérifiez que la clé API est correcte

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

2. Vérifiez les permissions de la clé API

   • La clé doit avoir les write ou all des permissions
   • Vérifiez dans le dashboard Capgo, rubrique API Keys

3. Assurez-vous que la clé API est bien lue

   # 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. Se réauthentifier

   bunx @capgo/cli@latest login

« App not found » ou « No permission for this app »

Symptômes :

• L'authentification fonctionne mais erreur spécifique à l'app

Solutions :

1. Vérifier que l'app est enregistrée

   bunx @capgo/cli@latest app list

2. Vérifier que l’ID de l’app correspond

   • Vérifier capacitor.config.json appId
   • S’assurer que la commande utilise le bon ID d’app

3. Vérifier l’accès à l’organisation

   • Vérifier que vous êtes dans la bonne organisation
   • La clé API doit avoir accès à l’organisation de l’app

Problèmes de build iOS

« Code signing failed »

Symptômes :

• Le build échoue à l'étape de signature de code
• Erreurs Xcode concernant les certificats ou les profils

Solutions :

1. Vérifiez la correspondance type de certificat / type de build

   • Builds de développement : certificats de développement requis
   • Les builds App Store nécessitent des certificats de distribution

2. Check certificate and profile match

   # 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. S'assurer que le profil de provisionnement est valide

   • Vérifiez la date d'expiration
   • Vérifiez qu'il inclut votre App ID
   • Vérifiez qu’il contient le certificat

4. Régénérer les identifiants

   • Supprimer l’ancien certificat/profil
   • En créer de nouveaux dans le portail Apple Developer
   • Re-coder et mettre à jour les variables d’environnement

« Provisioning profile doesn’t include signing certificate »

Symptômes :

• Xcode ne trouve pas le certificat dans le profil

Solutions :

1. Télécharger le dernier profil depuis Apple

   • Accédez à Apple Developer → Certificates, IDs & Profiles
   • Télécharger le profil de provisionnement
   • Vérifiez qu’il contient bien votre certificat

2. Vérifiez que le certificat figure dans le profil

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

3. Recréez le profil avec le bon certificat

   • Dans le portail Apple Developer, modifiez le profil
   • Assurez-vous que votre certificat de distribution est sélectionné
   • Téléchargez et réencodez

« App Store Connect authentication failed »

Symptômes :

• L'upload vers TestFlight échoue
• Erreurs de clé API

Solutions :

1. Vérifiez les identifiants de la clé API

   • Vérifiez APPLE_KEY_ID (doit comporter 10 caractères)
   • Vérifiez APPLE_ISSUER_ID (doit être au format UUID)
   • Vérifiez que APPLE_KEY_CONTENT est bien encodé en base64

2. Synchronisez l'horloge de votre ordinateur

   • L'authentification App Store Connect utilise des JWT à courte durée de vie générés à partir de l'heure de votre système local
   • Apple rejette les tokens dont l'expiration dépasse 20 minutes dans le futur ; un léger décalage d'horloge peut donc invalider une clé par ailleurs valide
   • Sur Windows, ouvrez Paramètres > Heure et langue > Date et heure et cliquez sur Sync now
   • Sur macOS, ouvrez Réglages Système > Général > Date et heure et activez l’heure automatique
   • Sur Linux, vérifiez timedatectl status et activez NTP si nécessaire
   • Après la synchronisation, relancez la commande de build ou de credentials Capgo

   See Apple’s Génération de tokens pour les requêtes API documentation de la règle de durée de vie du token App Store Connect.

3. Tester la clé API localement

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

4. Vérifiez les permissions de la clé API

   • La clé doit avoir le rôle « Developer » ou supérieur
   • Vérifiez dans App Store Connect -> Utilisateurs et accès -> Clés

5. Assurez-vous que la clé n'est pas révoquée

   • Vérifiez dans App Store Connect
   • Générez une nouvelle clé si nécessaire

L’app crash au lancement sur iOS 27

Symptômes :

• L'application compilée avec Xcode 27 se ferme immédiatement sur iOS 27 (TestFlight ou appareil)
• Le rapport de crash indique que _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Solution : les apps compilées avec le SDK iOS 27 doivent adopter le cycle de vie UIScene. Ajoutez un SceneDelegate et une UIApplicationSceneManifest vers ios/App/App/Info.plist, ou compilez avec --xcode-version 26. Capgo bloque désormais ces builds avant leur lancement (contrôle prescan ios/plist-scene-lifecycle-xcode27).

« Pod install failed »

Attention

Capgo Build arrête de compiler les projets CocoaPods en décembre 2026. Migrez vers Swift Package Manager : voir le Guide SPM Capacitor.

Symptômes :

• Le build échoue lors de l’installation de CocoaPods
• Erreurs dans le Podfile

Solutions :

1. Vérifier que Podfile.lock est commité

   git status ios/App/Podfile.lock

2. Tester pod install localement

   cd ios/App
   pod install

3. Vérifier les pods incompatibles

   • Vérifier le Podfile pour les conflits de version
   • Ensure all pods support your iOS deployment target

4. Vider le cache des pods

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

Problèmes de build Android

« Keystore password incorrect »

Symptômes :

• Le build échoue lors de la signature
• Erreurs Gradle liées au keystore

Solutions :

1. Vérifier le mot de passe du keystore

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

2. Vérifier les variables d’environnement

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

3. Vérifier l’encodage base64

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

« Key alias not found »

Symptômes :

• Échec de la signature avec une erreur d'alias

Solutions :

1. Lister les alias du keystore

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

2. Vérifier que l'alias correspond exactement

   • L'alias est sensible à la casse
   • Vérifier les fautes de frappe dans KEYSTORE_KEY_ALIAS

3. Utiliser le bon alias du keystore

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

« Gradle build failed »

Symptômes :

• Erreurs Gradle génériques
• Problèmes de compilation ou de dépendances

Solutions :

1. Testez d’abord le build localement

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Vérifiez les dépendances manquantes

   • Vérifiez les fichiers build.gradle
   • Assurez-vous que tous les plugins sont listés dans les dépendances

3. Vérifier la compatibilité de version Gradle

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

4. Vider le cache Gradle

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

« Play Store upload failed »

Symptômes :

• Le build réussit mais l’upload échoue
• Erreurs du compte de service

Solutions :

1. Vérifier le JSON du compte de service

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

2. Vérifier les permissions du compte de service

   • Aller dans la Play Console → Configuration → Accès API
   • Assurez-vous que le compte de service a accès à votre application
   • Accorder la permission « Publier sur les canaux de test »

3. Vérifiez que l'app est configurée dans la Play Console

   • L'application doit d'abord être créée dans la Play Console
   • Au moins un APK doit être envoyé manuellement au début

4. Vérifier que API est activé

   • L'API Google Play Developer doit être activée
   • Vérifier dans Google Cloud Console

Problèmes généraux

« Job not found » ou « Build status unavailable »

Symptômes :

• Impossible de vérifier l’état du build
• Erreurs d’ID de job

Solutions :

1. Patienter un instant et réessayer

   • Les jobs de build peuvent prendre quelques secondes à s’initialiser

2. Vérifiez que l’ID du job est correct

   • Vérifiez l’ID du job dans la réponse initiale du build

3. Vérifiez que le build n’a pas expiré

   • Build data is available for 24 hours

« Project sync failed »

Symptômes :

• Échec du build avant le début de la compilation
• Erreurs de fichiers manquants

Solutions :

1. Exécutez la synchronisation Capacitor localement

   bunx cap sync

2. Vérifiez que tous les fichiers natifs sont commités

   git status ios/ android/

3. Vérifiez les fichiers natifs ignorés par git

   • Examinez le fichier .gitignore
   • Ensure important config files aren’t ignored

« Build succeeded but I don’t see output »

Symptômes :

• Le build indique un succès mais aucun lien de téléchargement

Solutions :

1. Vérifier la configuration du build

   • Le stockage des artefacts peut ne pas être configuré
   • Contacter le support si l’accès aux artefacts est indisponible pour votre build

2. Pour la soumission sur TestFlight (iOS)

   • Vérifier App Store Connect
   • Le traitement peut prendre 5 à 30 minutes après l’upload

3. Pour le Play Store (Android)

   • Vérifier Play Console → Testing → Internal testing
   • Le traitement peut prendre quelques minutes

Le build a réussi mais l'artefact est incorrect après un changement d'environnement

Symptômes :

• Statut du build est success mais l’IPA/AAB/APK ne correspond pas à la branche ou au flavor que vous venez de compiler
• AAB Android manquant ou incorrect après changement des identifiants RC vs production ou --android-flavor
• Le build finit anormalement vite après changement de config de signature ou de product flavor

Cause : Capgo restaure le cache de build par application par défaut (omettre cache_key pour le cache général partagé). Si RC et production partagent le même ID d’application sans clés distinctes, une restauration peut réutiliser la sortie compilée de l’environnement précédent.

Solutions :

1. Utiliser une clé de cache par environnement (recommandé pour les pipelines RC/PROD en cours) :

   # 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. Forcer un build propre lors du débogage :

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

3. Dans API ou les intégrations webhook, passez cache_key (par exemple "prod") ou définissez cache_enabled: false pour une seule exécution propre.

Consultez Cache de build pour la référence complète des options.

Problèmes spécifiques au CI/CD

GitHub Actions : « Command not found »

Symptômes :

• bunx @capgo/cli@latest … échoue en CI avec l'erreur « command not found »

Solutions :

1. Configurez d'abord Bun pour que bunx soit disponible :

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

2. Ensuite, lancez CLI — bunx le récupère à la demande, sans installation globale :

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

GitHub Actions : « Secrets not found »

Symptômes :

• Variables d'environnement vides lors du build

Solutions :

1. Vérifier que les secrets sont configurés

   • Allez dans Settings du dépôt → Secrets and variables → Actions
   • Ajouter tous les secrets requis

2. Utiliser la syntaxe correcte

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

3. Vérifier la correspondance des noms de secrets

   • La casse est sensible aux noms
   • Aucune faute de frappe dans les références secrètes

Obtenir plus d'aide

Activer les logs détaillés

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

Collecter les informations de build

Lorsque vous contactez le support, indiquez :

1. Commande de build utilisée

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

2. Message d'erreur (sortie complète)

3. ID du job (d'après la sortie du build)

4. Logs de build (copiez la sortie complète du terminal)

5. Infos sur l'environnement

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

Contacter le support

• Discord: Rejoignez notre communauté
• E-mail: support@capgo.app
• Documentation: Docs Capgo

Limitations connues

Limitations actuelles :

• Temps de build maximal : 10 minutes
• Taille d’upload maximale : ~500 Mo
• iOS builds require 24-hour Mac leases, build on Mac will enqueue to ensure optimal usage
• La disponibilité du téléchargement des artefacts de build dépend de la destination du build et de la configuration du stockage des artefacts

Ces limitations peuvent être ajustées en fonction des retours.

Prescan a bloqué mon build

Capgo exécute un local pré-scan avant l’upload. Corrigez le problème signalé, ou ignorez uniquement cet identifiant de vérification :

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

Voir le catalogue complet : Vérifications prescan.

Ressources complémentaires

• Prise en main - Guide de configuration initiale
• Options de configuration - Flags CLI, notamment --cache-key et --no-cache
• Builds iOS - Configuration spécifique à iOS
• Builds Android - Configuration spécifique à Android
• Vérifications prescan - Full list of pre-build checks and ignore flags
• Référence CLI - Documentation complète des commandes