Risoluzione problemi

Soluzioni ai problemi comuni durante la build di app native con Capgo Cloud Build.

Errori di build

“Upload failed” o “Connection timeout”

Sintomi:

• La build fallisce durante l'upload del progetto
• Errori di timeout dopo 60 secondi

Soluzioni:

1. Controlla la connessione a Internet

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

2. Riduci la dimensione del progetto

   • Assicurati node_modules/ non viene caricato (dovrebbe essere escluso automaticamente)
   • Controlla se ci sono file pesanti nel progetto:

   find . -type f -size +10M

3. Verifica la scadenza dell'URL di upload

   • Gli URL di upload scadono dopo 1 ora
   • Se ricevi un errore di URL scaduto, riesegui il comando di build

Tip

I progetti molto grandi potrebbero toccare il limite di tempo di build (vedi Limitazioni note). Contatta il supporto per opzioni enterprise.

“Timeout della build dopo 10 minuti”

Sintomi:

• Il build supera il tempo massimo consentito
• Lo stato indica timeout

Soluzioni:

1. Ottimizza le dipendenze

   • Rimuovi i pacchetti npm inutilizzati
   • Usa npm prune --production prima del build

2. Controlla eventuali problemi di rete nel build

   • Alcune dipendenze potrebbero scaricare file pesanti durante il build
   • Valuta il pre-caching con un lock file

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 la tua app ha legittimamente bisogno di più tempo
   • Possiamo regolare i limiti per casi d'uso specifici

Problemi di autenticazione

“Chiave API non valida” o “Non autorizzato”

Sintomi:

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

Soluzioni:

1. Verifica che la chiave API sia corretta

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

2. Controlla i permessi della chiave API

   • La chiave deve avere write oppure all permessi
   • Controlla nel dashboard di Capgo sotto API Keys

3. Assicurati 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. Riautenticati

   bunx @capgo/cli@latest login

“App non trovata” o “Nessun permesso per questa app”

Sintomi:

• Autenticazione riuscita ma errore specifico dell'app

Soluzioni:

1. Verifica che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Controlla che l'app ID corrisponda

   • Verifica capacitor.config.json appId
   • Assicurati che il comando usi l'app ID corretto

3. Verifica l'accesso all'organizzazione

   • Verifica di essere nell'organizzazione corretta
   • La chiave API deve avere accesso all'organizzazione dell'app

Problemi con la build iOS

“Code: firma non riuscita”

Sintomi:

• Errore durante la fase di firma di code
• Errori Xcode relativi a certificati o profili

Soluzioni:

1. Verify certificate type matches build type

   • Le build Development richiedono certificati Development
   • Le build per l'App Store richiedono certificati Distribution

2. Verifica la corrispondenza tra certificato e profilo

   # 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 provisioning profile sia valido

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

4. Rigenera le credenziali

   • Elimina il vecchio certificato/profilo
   • Creane di nuovi nel portale Apple Developer
   • Ricodifica e aggiorna le variabili d'ambiente

“Provisioning profile non include il certificato di firma”

Sintomi:

• Xcode non trova il certificato nel profilo

Soluzioni:

1. Scarica l'ultimo profilo da Apple

   • Vai su Apple Developer → Certificates, IDs & Profiles
   • Scarica il provisioning profile
   • 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

   • Nel portale Apple Developer, modifica il profilo
   • Assicurati che sia selezionato il certificato di distribuzione
   • Scarica e ricodifica

“Autenticazione ad App Store Connect non riuscita”

Sintomi:

• Upload a TestFlight non riuscito
• Errori chiave API

Soluzioni:

1. Verifica le credenziali della chiave API

   • Controlla APPLE_KEY_ID (deve avere 10 caratteri)
   • Controlla APPLE_ISSUER_ID (deve essere in 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 durata generati dall'ora di sistema locale
   • Apple rifiuta i token che scadono oltre 20 minuti in futuro, quindi anche una piccola deriva dell'orologio può far fallire una chiave altrimenti valida
   • Su Windows, apri Impostazioni > Ora & lingua > Data & ora e clicca Sincronizza ora
   • Su macOS, apri Impostazioni di Sistema > Generali > Data & Ora e abilita l'ora automatica
   • Su Linux, verifica timedatectl status e abilita NTP se necessario
   • Dopo la sincronizzazione, riesegui il comando di build o credenziali di Capgo

   Consulta Apple Generazione di token per le richieste API documentazione sulla regola della durata del token di App Store Connect.

3. Testa la chiave API localmente

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

4. Controlla i permessi della chiave API

   • La chiave richiede il ruolo “Developer” o superiore
   • Verifica in App Store Connect -> Users and Access -> Keys

5. Assicurati che la chiave non sia stata revocata

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

L'app si blocca all'avvio su iOS 27

Sintomi:

• L'app compilata con Xcode 27 si chiude immediatamente su iOS 27 (TestFlight o dispositivo)
• Il report di crash mostra _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Soluzione: le app compilate con iOS 27 SDK devono adottare il ciclo di vita UIScene. Aggiungi un SceneDelegate e a una UIApplicationSceneManifest a ios/App/App/Info.plist, oppure compila con --xcode-version 26. Capgo ora blocca queste compilazioni prima che inizino (verifica prescan ios/plist-scene-lifecycle-xcode27).

“Pod install non riuscito”

Attenzione

Capgo Build smetterà di compilare progetti CocoaPods a dicembre 2026. Migra a Swift Package Manager: consulta il Capacitor guida SPM.

Sintomi:

• La build fallisce durante l'installazione di CocoaPods
• Errori nel Podfile

Soluzioni:

1. Verifica che Podfile.lock sia commitato

   git status ios/App/Podfile.lock

2. Testa pod install localmente

   cd ios/App
   pod install

3. Controlla i pod non compatibili

   • Controlla il Podfile per conflitti di versione
   • Assicurati che tutti i pod supportino il tuo deployment target iOS

4. Svuota la cache dei pod

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

Problemi di build su Android

“Password keystore errata”

Sintomi:

• La 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 d'ambiente

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

3. Verifica la codifica base64

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

“Key alias non trovato”

Sintomi:

• La firma fallisce per errore di alias

Soluzioni:

1. Elenca gli alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Controlla gli errori di battitura in KEYSTORE_KEY_ALIAS

3. Usa l'alias corretto dal keystore

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

“Gradle build failed”

Sintomi:

• Errori Gradle generici
• Problemi di compilazione o dipendenze

Soluzioni:

1. Testa prima la build localmente

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Controlla le dipendenze mancanti

   • Controlla 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. Svuota la cache di Gradle

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

“Upload su Play Store non riuscito”

Sintomi:

• La build riesce ma l'upload fallisce
• Errori account di servizio

Soluzioni:

1. Verifica il JSON del service account

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

2. Controlla i permessi del service account

   • Vai su Play Console → Setup → Accesso API
   • Assicurati che il service account abbia accesso all'app
   • Concedi il permesso “Release to testing tracks”

3. Verifica che l'app sia configurata in Play Console

   • L'app deve prima essere creata in Play Console
   • Inizialmente deve essere caricato manualmente almeno un APK

4. Controlla che API sia abilitato

   • L'API Google Play Developer deve essere abilitata
   • Verifica in Google Cloud Console

Problemi generali

“Job not found” o “Build status unavailable”

Sintomi:

• Impossibile controllare lo stato della build
• Errori nell'ID del job

Soluzioni:

1. Attendi un momento e riprova

   • I job di build possono richiedere qualche secondo per inizializzarsi

2. Verifica che l'ID del job sia corretto

   • Verifica il job ID nella risposta del build iniziale

3. Controlla che il build non sia scaduto

   • I dati del build sono disponibili per 24 ore

“Sincronizzazione del progetto fallita”

Sintomi:

• Il build fallisce prima dell'inizio della compilazione
• Errori di file mancanti

Soluzioni:

1. Esegui Capacitor sync localmente

   bunx cap sync

2. Assicurati che tutti i file nativi siano commitati

   git status ios/ android/

3. Controlla i file nativi ignorati da git

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

“Build riuscita ma non vedo l’output”

Sintomi:

• Build riuscita ma nessun link di download

Soluzioni:

1. Verifica la configurazione di build

   • Lo storage degli artifact potrebbe non essere configurato
   • Contatta il supporto se l'accesso agli artifact non è disponibile per la tua build

2. Per l'invio su iOS TestFlight

   • Verifica App Store Connect
   • L'elaborazione può richiedere da 5 a 30 minuti dopo l'upload

3. Per Android Play Store

   • Verifica Play Console → Testing → Internal testing
   • L'elaborazione può richiedere alcuni minuti

Build riuscita ma artifact errato dopo un cambio di ambiente

Sintomi:

• Stato del build è success ma l'IPA/AAB/APK non corrisponde al branch o al flavor appena buildato
• AAB Android mancante o errato dopo aver cambiato le credenziali RC vs produzione o --android-flavor
• La build finisce sospettosamente in fretta subito dopo aver cambiato signing config o product flavor

Causa: Capgo ripristina la cache di build per app di default (ometti cache_key per la cache generale condivisa). Se RC e produzione condividono lo stesso app ID senza chiavi separate, un restore può riutilizzare l'output compilato dell'ambiente precedente.

Soluzioni:

1. Usa una cache key per ogni ambiente (consigliato per pipeline RC/PROD attive):

   # 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 build pulita durante il debugging:

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

3. In API o nelle integrazioni webhook, passa cache_key (ad esempio "prod") o imposta cache_enabled: false per un singolo run pulito.

Vedi Cache di build per il riferimento completo alle opzioni.

Problemi specifici di CI/CD

Azioni GitHub: “Command not found”

Sintomi:

• bunx @capgo/cli@latest … fallisce in CI con “command not found”

Soluzioni:

1. Configura prima Bun quindi bunx è disponibile:

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

2. Poi esegui CLI — bunx lo scarica su richiesta, senza bisogno di installazione globale:

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

GitHub Actions: “Secrets non trovati”

Sintomi:

• Variabili d'ambiente vuote nel build

Soluzioni:

1. Verifica che i secrets siano impostati

   • Vai su Impostazioni del repo → Secrets and variables → Actions
   • Aggiungi tutti i segreti richiesti

2. Usa la sintassi corretta

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

3. Verifica che i nomi dei segreti corrispondano

   • I nomi distinguono tra maiuscole e minuscole
   • Nessun refuso nei riferimenti ai segreti

Ottenere ulteriore assistenza

Abilita il logging dettagliato

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

Raccogli informazioni sulla build

Quando contatti il supporto, includi:

1. Comando di build utilizzato

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

2. Messaggio di errore (output completo)

3. ID del job (dall'output di build)

4. Log di build (copia l'output completo del terminale)

5. Informazioni sull'ambiente

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

Contatta il supporto

• Discord: Unisciti alla nostra community
• Email: support@capgo.app
• Documentazione: Capgo Docs

Limitazioni note

Limitazioni attuali:

• Tempo massimo di build: 10 minuti
• Dimensione massima di upload: ~500MB
• Le build iOS richiedono lease Mac di 24 ore; la build su Mac viene messa in coda per garantire un utilizzo ottimale
• La disponibilità del download degli artefatti di build dipende dalla destinazione della build e dalla configurazione dello storage degli artefatti

Queste limitazioni potrebbero essere modificate in base ai feedback.

Prescan ha bloccato la build

Capgo esegue un prescan prima dell'upload. Correggi il problema segnalato o ignora solo quell'ID di controllo:

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

Consulta il catalogo completo: Controlli prescan.

Risorse aggiuntive

• Per iniziare - Guida alla configurazione iniziale
• Opzioni di configurazione - flag CLI, tra cui --cache-key e --no-cache
• Build iOS - Configurazione specifica per iOS
• Build Android - Configurazione specifica per Android
• Controlli prescan - Elenco completo dei controlli pre-build e delle flag di ignoramento
• Riferimento CLI - Documentazione completa dei comandi