Troubleshooting

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

Fallimenti di costruzione

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

Sintomi:

• Il caricamento del progetto fallisce
• Errori di timeout dopo 60 secondi

Solutions:

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
   • Se ottieni un errore di URL scaduto, ripeti il comando di costruzione

Tip

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

“Timeout di costruzione dopo 10 minuti”

Sintomi:

• Costruzione supera il tempo massimo consentito
• Lo stato mostra timeout

Soluzioni:

1. Optimizzare le dipendenze

   • Rimuovere pacchetti npm non utilizzati
   • Usare npm prune --production Prima di costruire

2. Check for network issues in build

   • 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. Contattare il supporto

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

Issue di autenticazione

“Chiave API non valida” o “Non autorizzato”

Sintomi:

• La costruzione 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 o all permessi
   • Verifica in Capgo dashboard sotto API Chiavi

3. Assicurati che la API chiave 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"

Symptoms:

• 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 ID dell'app
   • Ensure command uses correct app ID

3. Verifica l'accesso all'organizzazione

   • Controlla di essere nell'organizzazione corretta
   • API deve avere accesso all'organizzazione dell'app

Problemi di costruzione per iOS

“Code firma fallita”

Sintomi:

• La costruzione fallisce durante la fase di firma code
• Errori di Xcode sui certificati o sui profili

Soluzioni:

1. Verify certificate type matches build type

   • Il costruzione di sviluppo richiede certificati di sviluppo
   • Il costruzione per l'App Store richiede 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

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

4. Regenera le credenziali

   • Cancella il vecchio certificato/profilo
   • Creane di nuovi nel portale dello sviluppatore Apple
   • Ricodifica e aggiorna le variabili di ambiente

Profilo di provisioning non include certificato di firma

Sintomi:

• Xcode non trova il certificato nel profilo

Solutions:

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 Apple Developer portal, modifica il profilo
   • Assicurati che il tuo certificato di distribuzione sia selezionato
   • Scarica e ricodifica

“Autenticazione App Store Connect fallita”

Sintomi:

• L'invio a 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 (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
   • Apple rifiuta i token che scadono 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 l'orologio automatico
   • Su Linux, controlla timedatectl status e abilita NTP se necessario
   • Dopo aver sincronizzato, ripeti la costruzione o la richiesta di credenziali Capgo

   Vedi Apple's Genera token per le richieste di API. documentazione per la regola di durata del token di App Store Connect

3. Testa la chiave API 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
   • Controlla in App Store Connect -> Utenti e accesso -> Chiavi

5. Assicurati che la chiave non sia stata revocata.

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

App si blocca al lancio su iOS 27

Sintomi:

• L'applicazione costruita con Xcode 27 si chiude immediatamente su iOS 27 (TestFlight o dispositivo)
• Il rapporto di crash mostra _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Soluzione: Gli app costruiti con l'SDK iOS 27 devono adottare il ciclo di vita UIScene. Aggiungi un SceneDelegate e un UIApplicationSceneManifest per ios/App/App/Info.plist, o costruisci con --xcode-version 26.Capgo ora blocca questi build prima che inizino (verifica di pre-scansione) ios/plist-scene-lifecycle-xcode27).

Installazione del pod fallita

Attenzione

Capgo La costruzione dei progetti CocoaPods si ferma nel dicembre 2026. Migra al gestore di pacchetti Swift: consulta il Capacitor Guida SPM.

Sintomi:

• La costruzione fallisce durante l'installazione dei CocoaPods
• Errori del file Podfile

Soluzioni:

1. Verifica che Podfile.lock sia stato commesso.

   git status ios/App/Podfile.lock

2. Esegui test pod localmente

   cd ios/App
   pod install

3. Verifica la presenza di pod incompatibili

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

4. Pulisci cache dei pod

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

Problemi di costruzione Android

“La password del keystore è errata”

Sintomi:

• La costruzione 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. Controlla le variabili di ambiente

   # 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. Elencare gli alias del keystore

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

2. Verificare che l'alias corrisponda esattamente

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

3. Usa l'alias corretto dal keystore

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

“Esecuzione del build di Gradle fallita”

Sintomi:

• Errori di Gradle generici
• Issue di compilazione o di dipendenza

Soluzioni:

1. Costruisci un test locale prima

   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”

Segni e sintomi:

• Costruzione riuscita, ma caricamento fallito
• 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 su 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. Verify app is set up in Play Console

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

4. Verificare che API sia abilitato.

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

Problemi Generali

“Job non trovato” o “Stato di costruzione non disponibile”

Sintomi:

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

Soluzioni:

1. Aspetta un momento e riprova

   • Build jobs may take a few seconds to initialize

2. Controlla che l'ID del lavoro sia corretto

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

3. Controlla che il costruzione non sia scaduto

   • I dati di costruzione sono disponibili per 24 ore

“Il sincronizzazione del progetto è fallita”

Sintomi:

• Il costruzione fallisce prima che la compilazione inizi
• 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. Controlla i file nativi ignorati da Git

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

"Il build è riuscito ma non vedo l'output"

Segni e sintomi:

• Il build mostra successo ma nessun collegamento di download

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 su iOS

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

3. Per Store di Giocattoli Android

   • Controlla Console di Gioco → Test → Test interni
   • 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'applicazione 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. Ricompila da zero 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 impostare cache_enabled: false per un singolo esecuzione pulita.

Vedi Build cache per la riferimento completo delle opzioni.

Problemi specifici per CI/CD

GitHub Azioni: “Comando non trovato”

Sintomi:

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

Soluzioni:

1. Configura Bun in primo luogo così bunx è disponibile:

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

2. Esegui quindi il CLI. — bunx carica solo quando necessario, nessuna installazione globale richiesta

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

GitHub Azioni: “Segreti non trovati”

Symptoms:

• Variabili di ambiente vuote nella build

Solutions:

1. Verifica che i segreti siano impostati

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

2. Utilizza la sintassi corretta

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

3. Controlla che i nomi dei segreti corrispondano

   • Il nome è case-sensitive
   • Nessun errore di ortografia nelle referenze segrete

Ottenere Maggiore Aiuto

Abilita la registrazione dettagliata

# 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. Log dei build (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
• E-mail: supporto@capgo.app
• Documentazione: Capgo Documenti

Limitazioni note

Limitazioni correnti:

• Tempo massimo di costruzione: 10 minuti
• Dimensione massima di caricamento: ~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.

Prescan ha bloccato la mia costruzione

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

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

Vedi il catalogo completo: Vedi il catalogo completo:.

Controlli di prescan

• Sottosezione intitolata “Risorse aggiuntive” Guida di avvio iniziale
• - Guida di avvio iniziale Opzioni di configurazione. - CLI flag inclusi --cache-key e --no-cache
• Illicazioni iOS - Configurazione specifica per iOS
• Illicazioni Android - Configurazione specifica per Android
• Verifica pre-scan - Full list of pre-build checks and ignore flags
• Riferimento CLI - Documentazione completa della riga di comando