Troubleshooting

Solutions to common issues when building native apps with Capgo Cloud Build.

Échecs de construction

“Échec d'upload” ou “Dépassé de temps””

Symptômes :

• Build fails during project upload
• 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

   • Vérifiez node_modules/ n'est pas chargé (devrait être automatiquement exclu)
   • Vérifiez les gros fichiers 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, relancez la commande de build

Conseil

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

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

Symptômes :

• Build exceeds maximum allowed time
• Statut montre timeout

Solutions :

1. Optimisez les dépendances

   • Supprimez les packages npm inutilisés
   • Utilisez npm prune --production avant de construire

2. Check for network issues in build

   • Some dependencies may download large files during build
   • Pré-cacher 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

   • If your app legitimately needs more time
   • We can adjust limits for specific use cases

Problèmes d'authentification

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

Symptômes :

• L'erreur d'authentification empêche la construction
• 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 ou
   • Check in Capgo dashboard under API Keys

3. Vérifiez 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. Se réauthentifier

   bunx @capgo/cli@latest login

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

Symptômes :

• 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érifier 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

« L'Code signature a échoué »

Symptômes :

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

Solutions :

1. Verify certificate type matches build type

   • Development builds need Development certificates
   • 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. Ensure provisioning profile is valid

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

4. Régeneratez les informations d'identification

   • Supprimez le certificat/profil ancien
   • Créez de nouveaux dans le portail Apple Developer
   • Récoder et mettre à jour les variables d'environnement

Le profil de provisionnement ne contient pas le certificat de signature

Symptômes :

• Xcode ne trouve pas de certificat dans le profil

Solutions :

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

   • Accédez à Apple Developer → Certificats, IDs et Profils
   • Télécharger le profil de provisionnement
   • Vérifiez 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
   • Vérifiez que votre certificat de distribution est sélectionné
   • Télécharger et ré-encoder

“L'authentification d'App Store Connect a échoué”

Symptômes :

• Échec de l'envoi vers TestFlight
• API clés d'erreur

Solutions :

1. Vérifiez les clés de sécurité 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 correctement encodé en base64

2. Synchronisez l'horloge de votre ordinateur

   • App Store Connect authentication uses short-lived JWTs generated from your local system time
   • Apple rejette les jetons qui expirent dans plus de 20 minutes à l'avenir, donc même un léger décalage horaire peut faire échouer une clé valide
   • Sur Windows, ouvrez Paramètres > Heure et langue > Date et heure et cliquez 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 Capgo commande de build ou de connexion.

   See Apple’s Génération de jetons pour les requêtes API Documentation pour la durée de vie du jeton 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érifier les permissions de la clé API.

   • Key needs “Developer” role or higher
   • Vérifier dans App Store Connect -> Utilisateurs et accès -> Clés.

5. S'assurer que la clé n'est pas révoquée.

   • Vérifier dans App Store Connect.
   • Générer une nouvelle clé si nécessaire.

“L'installation de Pod a échoué”.

Symptômes :

• L'installation de CocoaPods se termine par un échec
• Les erreurs de Podfile

Solutions :

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

   git status ios/App/Podfile.lock

2. Tester l'installation de pod localement

   cd ios/App
   pod install

3. Vérifiez les pods incompatibles

   • Vérifiez les conflits de versions dans Podfile
   • 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 construction Android

Mot de passe de clé de stockage incorrect

Symptômes :

• La construction faille lors de la signature
• Erreurs Gradle concernant le coffre de clés

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 :

• Signature échoue avec 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. Utiliser l'alias correct issu du coffre de clés

   # 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

   • Examinez les fichiers build.gradle
   • Ensure all plugins are listed in dependencies

3. Verify Gradle version compatibility

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

4. Vider le cache Gradle

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

“Échec de l'upload sur Google Play”

Symptômes :

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

Solutions :

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

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

2. Check service account permissions

   • Allez à la Console de jeu → Paramètres → API Accès
   • Ensure service account has access to your app
   • Accordez la permission « Lancer dans les pistes de test »

3. Verify app is set up in Play Console

   • App must be created in Play Console first
   • Au moins un APK doit être téléchargé manuellement initialement

4. Vérifiez que API est activé

   • Google Play Developer API doit être activé
   • Vérifiez dans la console Google Cloud

Problèmes généraux

“Job not found” or “Build status unavailable”

Symptômes :

• Impossible de vérifier le statut de construction
• Erreurs d'ID de job

Solutions :

1. Attendez un moment et réessayez

   • Build jobs may take a few seconds to initialize

2. Vérifiez que l'ID de job est correct

   • Verify the job ID from the initial build response

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

   • Build data is available for 24 hours

“La synchronisation du projet a échoué”

Symptômes :

• Build fails before compilation starts
• Erreurs de fichiers manquants

Solutions :

1. Exécutez la synchronisation locale de Capacitor

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Check for gitignored native files

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

“Build succeeded but I don’t see output”

Symptoms:

• Build shows success but no download link

Solutions:

1. Vérifiez la configuration de construction

   • Artifact storage may not be configured
   • Contactez le support si l'accès aux artefacts est indisponible pour votre build

2. For la soumission de TestFlight iOS

   • Vérifiez App Store Connect
   • La mise en œuvre peut prendre 5-30 minutes après l'upload.

3. For la soumission de Play Store Android

   • Vérifiez Play Console → Testing → Test interne
   • Processing may take a few minutes

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

Symptômes :

• Le statut de build est success Mais l'IPA/AAB/APK ne correspond pas à la branche ou au goût que vous venez de construire.
• Manque ou mauvais fichier AAB Android après changement de clés RC vs production ou --android-flavor
• Build finishes suspiciously fast right after changing signing config or product flavor

Cause : Capgo restaure la cache de construction par application par défaut (omettre cache_key pour le cache général partagé). Si RC et production partagent la 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. Effectuer une construction nettoyante lors du débogage :

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

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

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

Problèmes spécifiques aux CI/CD

GitHub Actions : “Commande non trouvée”

Symptômes :

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

Solutions :

1. Configurez d’abord Bun so bunx soit disponible :

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

2. Ensuite exécutez le CLI — bunx fetches it on demand, no global install needed:

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

GitHub Actions: “Secrets not found”

Symptômes :

• Environment variables empty in build

Solutions :

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

   • Allez dans les Paramètres du 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
   • Aucun faute d'orthographe dans les références de secrets

Obtenir plus d'aide

Activer la journalisation détaillée

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

Collecter les informations de construction

When contacting support, include:

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 (from sortie de l'output de build)

4. Build logs Copiez l'ensemble de l'output 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: Capgo Docs

Limites connues

Limites actuelles :

• Temps de construction maximum : 10 minutes
• Taille maximale de téléchargement : ~500Mo
• iOS builds require 24-hour Mac leases, build on Mac will enqueue to ensure optimal usage
• Build artifact download availability depends on build destination and artifact storage configuration

These limitations may be adjusted based on feedback.

Le prescan m'a bloqué ma build

Capgo exécute un prescan local prescan Avant l'envoi. Corrigez le problème signalé ou ignorez uniquement ce contrôle d'ID :

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

Voir le catalogue complet : Vérifications préalables.

Ressources supplémentaires

• Prise en main - 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érification préalable - Full list of pre-build checks and ignore flags
• Référence CLI - Documentation complète de la commande