Troubleshooting

Soluzioni per i problemi comuni quando si costruiscono applicazioni native con Capgo Cloud Build.

Fallimenti di costruzione

“Fallito l'upload” o “Timeout di connessione”

Sintomi:

• Build fails during project upload
• Errori di timeout dopo 60 secondi

Soluzioni:

1. Controlla la tua connessione internet

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

2. Riduci la dimensione del progetto

   • Assicurati node_modules/ non stia caricando (dovrebbe essere escluso automaticamente)
   • Controlla i file grandi nel tuo progetto:

   find . -type f -size +10M

3. Controlla la scadenza dell'URL di caricamento

   • Gli URL di caricamento scadono dopo 1 ora
   • If si ottiene un errore di URL scaduto, riprovare con il comando di costruzione

Consiglio

Very large projects may hit the build-time limit (see Limitazioni noteContattare il supporto per opzioni aziendali.

“Timeout di costruzione dopo 10 minuti”

Sintomi:

• La costruzione supera il tempo massimo consentito
• Lo stato mostra timeout

Soluzioni:

1. Optimizza dipendenze

   • Elimina pacchetti inutilizzati npm
   • Usa npm prune --production prima di costruire

2. Controlla problemi di rete durante la costruzione

   • Alcune dipendenze possono scaricare file grandi durante la costruzione
   • Considera il pre-caching con un file di blocco

3. Verifica le dipendenze native

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

4. Contatta il supporto

   • Se il tuo app ha effettivamente bisogno di più tempo
   • Potremmo regolare i limiti per casi d'uso specifici

Problemi di autenticazione

“API chiave non valida” o “Non autorizzato”

Sintomi:

• La costruzione fallisce immediatamente con un errore di autenticazione
• Errori 401 o 403

Soluzioni:

1. Verifica che la API chiave sia corretta

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

2. Verifica le API autorizzazioni chiave

   • La chiave deve avere write o all permissions
   • Controlla nel Capgo dashboard sotto API Chiavi

3. Assicurarsi che la chiave API venga letta

   # 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 non trovata" o "Nessuna autorizzazione per questa app"

Sintomi:

• Authentication works but app-specific error

Soluzioni:

1. Verifica che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Controlla che l'ID dell'app corrisponda

   • Verifica capacitor.config.json appId
   • Ensure command uses correct app ID

3. Verifica l'accesso all'organizzazione

   • Controlla di essere nella organizzazione corretta
   • La chiave API deve avere accesso all'organizzazione dell'app

I Problemi di Costruzione per iOS

“La firma con Code è fallita”

Sintomi:

• Il build fallisce durante la fase di firma code.
• Error Xcode relativi a certificati o profili

Soluzioni:

1. Verify certificate type matches build type

   • I build di sviluppo richiedono certificati di sviluppo
   • Le costruzioni dell'App Store richiedono certificati di distribuzione

2. Controlla certificato e profilo di corrispondenza

   # 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. Assicurati che il profilo di provisioning sia valido

   • Verifica la data di scadenza
   • Verifica che includa il tuo ID App
   • Conferma che includa il certificato

4. Regenera le credenziali

   • Elimina il vecchio certificato/profilo
   • Crea nuovi in Apple Developer portal
   • Riaccodifica e aggiorna le variabili di ambiente

Profilo di provisioning non include certificato di firma

Sintomi:

• Xcode non riesce a trovare il certificato nel profilo

Soluzioni:

1. Scarica il profilo più recente da Apple

   • Vai a Apple Developer → Certificati, ID e Profili
   • Scarica il profilo di provisioning
   • Assicurati che includa il tuo certificato

2. Verifica che il certificato sia nel profilo

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

3. Ricrea il profilo con il certificato corretto

   • In portallo sviluppatore Apple, modifica il profilo
   • Assicurati di aver selezionato il certificato di distribuzione
   • Scarica e ricodifica

“Autenticazione App Store Connect fallita”

Sintomi:

• La pubblicazione su TestFlight fallisce
• Errori relativi alla chiave API

Soluzioni:

1. Verifica le credenziali della chiave API

   • Controlla APPLE_KEY_ID (dovrebbe essere di 10 caratteri)
   • Controlla APPLE_ISSUER_ID (che dovrebbe essere nel formato UUID)
   • Verifica che APPLE_KEY_CONTENT sia correttamente codificato in base64

2. Sincronizza l'orologio del computer

   • L'autenticazione di App Store Connect utilizza JWT a breve scadenza generati dal tempo del sistema locale
   • Gli Apple rifiutano i token che scadranno dopo più di 20 minuti, quindi anche piccoli disallineamenti orari possono rendere un altrimenti valido token non valido
   • Su Windows, apri Impostazioni > Tempo e lingua > Data e ora > e clicca Sincronizza ora
   • Su macOS, apri Impostazioni del sistema > Generale > Data e ora > e abilita la sincronizzazione automatica dell'orologio
   • On Linux, controlla timedatectl status e abilita NTP se necessario
   • Dopo aver sincronizzato, esegui nuovamente il Capgo build o il comando delle credenziali

   Vedi Apple’s Testa la chiave API localmente documentazione per la regola di durata del token di App Store Connect

3. Test chiave API in locale

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

4. Controlla le autorizzazioni della chiave API

   • Key needs “Developer” role or higher
   • Verifica in App Store Connect -> Utenti e accessi -> Chiavi

5. Assicurati che la chiave non sia revocata

   • Controlla su App Store Connect
   • Genera una nuova chiave se necessario

“Installazione Pod fallita”

Sintomi:

• Il build fallisce durante l'installazione di CocoaPods
• Errori in Podfile

Soluzioni:

1. Verifica che Podfile.lock sia commesso

   git status ios/App/Podfile.lock

2. Esegui installazione pod localmente

   cd ios/App
   pod install

3. Verifica per pods incompatibili

   • Verifica Podfile per conflitti di versione
   • Assicurarsi che tutti i pod supportino la versione di destinazione iOS

4. Pulisci cache pod

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

Problemi di costruzione Android

“Password della chiave segreta sbagliata”

Sintomi:

• Il build fallisce durante la firma
• Errori Gradle relativi al keystore

Soluzioni:

1. Verifica la password del keystore

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

2. Controlla le variabili di ambiente

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

3. Verifica l'encoding base64

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

“Alias della chiave non trovato”

Sintomi:

• La firma fallisce con errore di alias

Soluzioni:

1. Elenco alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Check for typos in KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

“Errore di build di Gradle”

Sintomi:

• Errori di Gradle generici
• Problemi di compilazione o di dipendenze

Soluzioni:

1. Testa prima il build locale

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Verifica la presenza di dipendenze mancanti

   • Rivista i file build.gradle
   • Assicurati che tutti i plugin siano elencati nelle dipendenze

3. Verifica la compatibilità della versione di Gradle

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

4. Pulisci il cache di Gradle

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

“Fallito l'upload su Play Store”

Sintomi:

• Il build ha successo ma l'upload fallisce
• Errori di account di servizio

Soluzioni:

1. Verifica il file JSON dell'account di servizio

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

2. Controlla i permessi dell'account di servizio

   • Vai a Console di Gioco → Impostazioni → API Accesso
   • Assicurati che l'account di servizio abbia accesso alla tua app
   • Concedi il permesso di rilascio per le tracce di testing

3. Verifica che l'app sia configurata nel Console Gioco

   • L'app deve essere creata inizialmente nel Console di Gioco
   • Deve essere caricato almeno un APK manualmente inizialmente

4. Verifica che API sia abilitato

   • Il API del Developer di Google Play deve essere abilitato
   • Verifica nel Console di Cloud di Google

Problemi Generali

“Non trovato il lavoro” o “Stato di costruzione non disponibile”

Sintomi:

• Impossibile verificare lo stato di costruzione
• Errori di ID del lavoro

Soluzioni:

1. Aspetta un momento e riprova

   • Build jobs may take a few seconds to initialize

2. Controlla che l'ID del job sia corretto

   • Verifica l'ID del job dalla risposta di costruzione iniziale

3. Controlla che la costruzione non sia scaduta

   • I dati di costruzione sono disponibili per 24 ore

“La sincronizzazione del progetto è fallita”

Sintomi:

• La costruzione fallisce prima che inizi la compilazione
• Errori di file mancanti

Soluzioni:

1. Esegui Capacitor in locale sincronizzando

   bunx cap sync

2. Assicurati che tutti i file nativi siano commessi

   git status ios/ android/

3. Verifica i file nativi ignorati da Git

   • Revisiona .gitignore
   • Ensure important config files aren’t ignored

“Il build è riuscito ma non vedo l'output”

Sintomi:

• Build shows success but no download link

Soluzioni:

1. Controlla la configurazione della costruzione

   • Artifact storage may not be configured
   • Contatta il supporto se l'accesso agli artefatti non è disponibile per la tua build

2. Per la sottoscrizione di TestFlight per iOS

   • Per la sottoscrizione di TestFlight per iOS
   • Il processo potrebbe richiedere 5-30 minuti dopo l'upload

3. Per Problemi di Android Store

   • Per la sottoscrizione di Play Store per Android
   • Il processo potrebbe richiedere alcuni minuti

Costruzione riuscita ma l'artifact è sbagliato dopo un cambio di ambiente

Sintomi:

• Lo stato di costruzione è success ma l'IPA/AAB/APK non corrisponde alla branch o al flavor che hai appena costruito
• L'AAB Android mancante o sbagliato dopo aver cambiato le credenziali RC vs produzione o --android-flavor
• Il build termina in modo sospetto velocemente appena si cambia la configurazione di firma o il flavor del prodotto.

Causa: Capgo ripristina il cache di costruzione per-app di default (omissione cache_key per il cache generale condiviso). Se RC e produzione condividono lo stesso ID dell'app senza chiavi separate, un ripristino può riutilizzare l'output compilato dal precedente ambiente.

Soluzioni:

1. Usa una chiave di cache per ambiente (consigliato per pipeline RC/PROD in corso):

   # 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. Forza una costruzione pulita quando si debugga:

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

3. In API o integrazioni webhook, passa cache_key (ad esempio "prod"o) o set cache_enabled: false per una sola esecuzione pulita.

Vedi Build cache per la riferimento completo delle opzioni.

Issue specifici del CI/CD

GitHub Azioni: “Comando non trovato”

Sintomi:

• bunx @capgo/cli@latest … fallisce in CI con “comando non trovato”

Soluzioni:

1. Configura Bun prima di tutto quindi bunx è disponibile:

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

2. Esegui quindi il CLI — bunx lo carica a richiesta, non è necessaria l'installazione globale:

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

GitHub Azioni: "Segreti non trovati"

Sintomi:

• Variabili di ambiente vuote in fase di costruzione

Soluzioni:

1. Verifica che i segreti siano impostati

   • Vai alle impostazioni del repository → Segreti e variabili → Azioni
   • Aggiungi tutti i segreti richiesti

2. Usa la sintassi corretta

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

3. Controlla che i nomi dei segreti corrispondano

   • I nomi sono case-sensitive
   • Nessun errore di ortografia nelle referenze ai segreti

Ottenere Maggiore Aiuto

Abilita Registro dei Log Dettagliato

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

Raccogli informazioni di costruzione

Quando si contatta il supporto, includere:

1. Comando di costruzione utilizzato

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

2. Messaggio di errore (output completo)

3. ID del lavoro (dal output di costruzione)

4. Build logs (copia l'output del terminale completo)

5. Informazioni sull'ambiente

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

Contattare il Supporto

• Discord: Unisciti alla nostra community
• Email: supporto@capgo.app
• Documentation: Capgo Documenti

Limitazioni note

Limitazioni attuali:

• Tempo di costruzione massimo: 10 minuti
• Dimensione massima dell'upload: ~500MB
• I costruzioni per iOS richiedono leasing Mac di 24 ore, costruisci su Mac per assicurare l'uso ottimale
• Build artifact download availability depends on build destination and artifact storage configuration

Queste limitazioni possono essere adattate in base alle risposte dei utenti.

Il prescan ha bloccato la mia costruzione

Capgo esegue una costruzione locale prescan prima dell'upload. Correggi il trovare segnalato, o ignora solo quel controllo id:

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

Vedi il catalogo completo: Verifica prescan.

Risorse aggiuntive

• Avvio rapido - Guida di avvio iniziale
• Opzioni di configurazione - flag CLI inclusi --cache-key e --no-cache
• Costruzioni iOS - Configurazione specifica per iOS
• Istruzioni per la costruzione Android - Configurazione specifica per Android
• Verifica pre-scansione - Full list of pre-build checks and ignore flags
• Riferimento CLI - Documentazione completa della riga di comando