Troubleshooting

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

Échecs de construction

Échec de l'upload ou temps d'attente de connexion

Symptômes :

• La construction faille pendant l'upload du projet
• Erreurs de temps limite après 60 secondes

Solutions :

1. Vérifiez votre connexion Internet

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

2. Réduire la taille du projet

   • S'assurer node_modules/ ne sont pas chargés (devraient être exclus automatiquement)
   • Vérifiez les fichiers volumineux dans votre projet :

   find . -type f -size +10M

3. Vérifiez l'expiration de l'URL de chargement

   • Les URL de chargement expirent après 1 heure
   • Si vous obtenez une erreur d'URL expirée, réexécutez la commande de build

Conseil

Very large projects may hit the build-time limit (see Limites connues). Contactez le support pour des options d'entreprise.

“Délai de construction après 10 minutes”

Symptômes :

• La construction dépasse le temps maximum autorisé
• Statut affiche timeout

Solutions :

1. Optimisez les dépendances

   • Supprimez les packages npm inutilisés
   • Utilisez npm prune --production avant la construction

2. Check for network issues in build

   • Some dependencies may download large files during build
   • Pré-cachez avec un fichier de verrouillage

3. Examinez les dépendances natives

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

4. Contactez le support

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

Issues d'authentification

“Clé API invalide” ou “Non autorisé””

Symptômes :

• La construction échoue immédiatement avec une erreur d'authentification
• 401 ou 403 erreurs

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 write ou all permissions
   • Check in Capgo dashboard under API Keys

3. Assurez-vous que la clé API est 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. Re-authenticate

   bunx @capgo/cli@latest login

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

Symptoms:

• Authentication works but app-specific error

Solutions :

1. Vérifiez que l'application est enregistrée

   bunx @capgo/cli@latest app list

2. Vérifiez que l'ID de l'application correspond

   • Vérifiez capacitor.config.json appId
   • Ensure command uses correct app ID

3. Vérifiez l'accès à l'organisation

   • Vérifiez que vous êtes dans l'organisation correcte
   • API doit avoir accès à l'organisation de l'application

Problèmes de construction iOS

« Code : signature échouée »

Symptômes :

• Build fails during code signing phase
• Erreurs Xcode concernant les certificats ou les profils

Solutions :

1. Vérifiez que le type de certificat correspond au type de build

   • Les builds de développement nécessitent des certificats de développement
   • App Store builds need Distribution certificates

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. Vérifiez que le profil de provisionnement est valide

   • Vérifiez la date d'expiration
   • Vérifiez qu'il inclut votre ID d'application
   • Confirmez qu'il inclut le certificat

4. Ré-générez les informations d'identification

   • Supprimez le certificat/le profil ancien
   • Créez de nouveaux dans le portail Apple Developer
   • Re-encodez et mettez à jour les variables d'environnement

Le profil de provisionnement ne contient pas de certificat de signature

Symptômes :

• Xcode ne trouve pas de certificat dans le profil

Solutions :

1. Télécharger le dernier profil d'Apple

   • Allez dans Apple Developer → Certificats, IDs et Profils
   • Télécharger le profil de provisionnement
   • Assurez-vous qu'il inclut votre certificat

2. Vérifiez que le certificat est 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éer le profil avec le certificat correct

   • Dans le portail Apple Developer, éditez le profil
   • Assurez-vous que votre certificat de distribution est sélectionné
   • Télécharger et re-encoder

“Échec d'authentification App Store Connect”

Symptômes :

• L'envoi vers TestFlight échoue
• Les erreurs de clé API

Solutions :

1. Vérifiez les clés de compte API

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

2. Synchronisez l'horloge de votre ordinateur

   • L'authentification App Store Connect utilise des jetons JWT à durée de vie courte générés à partir de l'heure système locale.
   • Apple rejette les jetons qui expirent dans plus de 20 minutes à l'avenir, donc même un petit décalage horaire peut rendre un clé valide inutilisable
   • 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 la synchronisation automatique de l'heure
   • Sur Linux, vérifiez timedatectl status et activez NTP si nécessaire
   • Après synchronisation, relancez la commande de build ou de credenciaux Capgo

   Voir l'Apple Génération de jetons pour les requêtes API Documentation pour la durée de vie du jeton App Store Connect.

3. Testez 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

   • Key needs “Developer” role or higher
   • 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'application s'effondre à l'exécution sur iOS 27

Symptômes :

• L'application construite avec Xcode 27 se ferme immédiatement sur iOS 27 (TestFlight ou appareil)
• Le rapport de panne montre _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Solution : les applications construites avec l'iOS 27 SDK doivent adopter le cycle de vie de UIScene. Ajoutez un SceneDelegate et un UIApplicationSceneManifest pour ios/App/App/Info.plistou construire avec --xcode-version 26.Capgo bloque maintenant ces builds avant leur démarrage (vérification avant lancement) ios/plist-scene-lifecycle-xcode27).

“L'installation de pod a échoué”

Attention

Capgo La construction s'arrête de construire des projets CocoaPods en décembre 2026. Migratez vers le gestionnaire de packages Swift : voir le Capacitor Guide SPM.

Symptômes :

• Échec de la construction pendant l'installation de CocoaPods
• Erreurs de Podfile

Solutions :

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

   git status ios/App/Podfile.lock

2. Testez l'installation de pod localement

   cd ios/App
   pod install

3. Vérifiez les pods incompatibles

   • Vérifiez les conflits de version dans le Podfile
   • Assurez-vous que tous les pods supportent votre cible de déploiement iOS

4. Effacer le cache de pod

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

Problèmes de construction Android

Clé de chiffrement du keystore incorrecte

Symptômes :

• La construction faille pendant la signature
• Erreurs Gradle concernant la clé de stockage

Solutions :

1. Vérifiez le mot de passe du coffre-fort

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

2. Vérifiez 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érifiez l'encodage base64

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

“Alias de clé non trouvé”

Symptômes :

• L'authentification échoue avec un erreur d'alias

Solutions :

1. Liste d'alias de clés de coffre

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

2. Vérifier que l'alias correspond exactement

   • L'alias est sensible à la casse
   • Check for typos in KEYSTORE_KEY_ALIAS

3. Utilisez l'alias correct de la clé de magasin

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

“La construction Gradle a échoué”

Symptômes :

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

Solutions :

1. Testez la construction locale avant

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Vérifiez les dépendances manquantes

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

3. Compatibilité de la version de Gradle

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

4. Effacer le cache Gradle

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

“Échec de l'envoi vers Google Play Store”

Symptômes :

• La construction réussit mais l'upload échoue
• Erreurs de compte de service

Solutions :

1. Vérifiez le fichier JSON de compte de service

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

2. Vérifiez les permissions du compte de service

   • Allez dans le Console de Play → Paramètres → Accès API
   • Assurez-vous que le compte de service a accès à votre application
   • Accordez la permission « Lancer dans les trajectoires de test »

3. Verify app is set up in Play Console

   • L'application doit être créée dans le console de Play avant
   • Au moins un APK doit être téléchargé manuellement initialement

4. Vérifiez que API est activé

   • Le compte Google Play Developer API doit être activé
   • Vérifiez dans le console de Cloud Google

Problèmes généraux

“Emploi non trouvé” ou “Statut de construction indisponible”

Symptômes :

• Impossible de vérifier le statut de construction
• Erreurs de ID de travail

Solutions :

1. Attendez un instant et réessayez

   • Build jobs may take a few seconds to initialize

2. Vérifiez que l'ID de la tâche est correct

   • Vérifiez l'ID de la tâche à partir de la réponse de construction initiale

3. Vérifiez que la construction n'est pas expirée

   • Build data is available for 24 hours

“La synchronisation du projet a échoué”

Symptômes :

• La construction fail avant le début de la compilation
• Erreurs de fichiers manquants

Solutions :

1. Exécutez Capacitor en local en mode synchronisé

   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

   • Vérifiez le fichier .gitignore
   • Ensure important config files aren’t ignored

« Le build a réussi mais je ne vois pas d'output »

Symptômes :

• Build shows success but no download link

Solutions :

1. Vérifiez la configuration de la construction

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

2. Pour la soumission à TestFlight sur iOS

   • Pour la soumission de TestFlight iOS
   • La mise en œuvre peut prendre 5-30 minutes après l'upload.

3. Pour Google Play Store Android

   • Pour la boutique Play Store Android
   • Vérifiez Play Console → Tests → Tests internes →

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

Symptômes :

• Le statut de construction est success mais l'IPA/AAB/APK ne correspond pas à la branche ou au goût que vous venez de construire
• Manque ou mauvaise AAB Android après basculement de clés RC vs production --android-flavor
• La construction se termine de manière suspecte juste après avoir changé la configuration de signature ou le goût du produit

Cause : Capgo restaure le cache de construction 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 séparées, une restauration peut réutiliser les résultats compilés de l'environnement précédent.

Solutions :

1. Utilisez 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 une construction nette Forcez une construction nette

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

3. Dans API ou intégrations par webhook, pass cache_key passer (par exemple "prod") ou définir cache_enabled: false pour une exécution propre et unique.

Voir Build cache pour la référence complète des options.

Problèmes spécifiques CI/CD

GitHub Actions : “Commande non trouvée”

Symptômes :

• bunx @capgo/cli@latest … échoue en CI avec “commande non trouvée”

Solutions :

1. Configurez d'abord Bun donc bunx est disponible :

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

2. Ensuite, exécutez le CLI — bunx Récupère-l’à la demande, aucune installation globale n'est nécessaire.

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

GitHub Actions : « Secrets non trouvés »

Symptômes :

• Environment variables empty in build

Solutions :

1. Vérifiez que les secrets sont définis

   • Allez dans les paramètres de votre dépôt → Secrets et variables → Actions
   • Ajoutez tous les secrets requis

2. Utilisez la syntaxe correcte

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

3. Vérifiez que les noms de secrets correspondent

   • Les noms sont sensibles à la casse
   • Les noms sont sensibles à la casse

Obtenir plus d'aide

Section intitulée « Obtenez plus d'aide »

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

Collecter les informations de construction

Lorsque vous contactez le support, incluez :

1. Commande de construction utilisée

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

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

3. ID de tâche (à partir de l'output de construction)

4. Build logs (copier la sortie complète du terminal)

5. Informations sur l'environnement

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

Contactez le support

• Discord: Rejoignez notre communauté
• Courriel: support@capgo.app
• Documentation: Docs de Capgo

Limitations connues

Limitations actuelles :

• Durée maximale de construction : 10 minutes
• Taille maximale de téléchargement : ~500 Mo
• Les builds iOS nécessitent des locations Mac de 24 heures, les builds sur Mac seront enregistrés pour optimiser l'utilisation.
• La disponibilité du téléchargement de l'artefact de build dépend de la configuration de destination de build et de stockage d'artefact.

Ces limitations peuvent être ajustées sur la base des retours d'information.

Prescan a bloqué ma construction

Capgo exécute une instance locale préscan avant l'envoi. Corrigez la constatation signalée ou ignorez uniquement ce contrôl’id :

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

Voir le catalogue complet : Vérifications de préscan.

Ressources supplémentaires

• Getting Started - Guide de configuration initiale
• Options de configuration - Drapeaux CLI incluant --cache-key et --no-cache
• Constructions iOS - Configuration spécifique à iOS
• Constructions Android - Configuration spécifique à Android
• Vérifications avant la prescan - Full list of pre-build checks and ignore flags
• CLI Référence - Documentation complète de la commande