Solución de problemas

Soluciones a problemas comunes al compilar apps nativas con Capgo Cloud Build.

Errores de compilación

“Upload failed” o “Connection timeout”

Síntomas:

• El build falla durante la subida del proyecto
• Errores de timeout tras 60 segundos

Soluciones:

1. Comprueba tu conexión a internet

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

2. Reduce el tamaño del proyecto

   • Ensure node_modules/ no se esté subiendo (debería excluirse automáticamente)
   • Revisa si hay archivos grandes en tu proyecto:

   find . -type f -size +10M

3. Verificar caducidad de la URL de upload

   • Las URLs de subida caducan a la hora
   • Si recibes un error de URL caducada, vuelve a ejecutar el comando de build

Consejo

Los proyectos muy grandes pueden alcanzar el límite de tiempo de build (ver Limitaciones conocidas). Contacta con soporte para opciones empresariales.

“Error de tiempo de espera tras 10 minutos de build”

Síntomas:

• El build supera el tiempo máximo permitido
• El estado muestra timeout

Soluciones:

1. Optimiza dependencias

   • Elimina los paquetes de npm no utilizados
   • Usa npm prune --production antes de compilar

2. Revisa problemas de red en el build

   • Algunas dependencias pueden descargar archivos grandes durante el build
   • Considera pre-cachear con un lock file

3. Revisa las dependencias nativas

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

4. Contactar con soporte

   • Si tu app realmente necesita más tiempo
   • Podemos ajustar los límites para casos de uso concretos

Problemas de autenticación

“API key invalid” o “Unauthorized”

Síntomas:

• El build falla inmediatamente con un error de autenticación
• Errores 401 o 403

Soluciones:

1. Verifica que la clave API sea correcta

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

2. Revisa los permisos de la clave API

   • La clave debe tener write o all permisos
   • Revisa el dashboard de Capgo en API Keys

3. Asegúrate de que se esté leyendo la clave API

   # 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. Reautenticarse

   bunx @capgo/cli@latest login

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

Síntomas:

• Autenticación funciona, pero error específico de la app

Soluciones:

1. Verifica que la app esté registrada

   bunx @capgo/cli@latest app list

2. Comprueba que coincida el app ID

   • Verifica capacitor.config.json appId
   • Comprueba que el comando use el app ID correcto

3. Verifica el acceso a la organización

   • Comprueba que estás en la organización correcta
   • La clave API debe tener acceso a la organización de la app

Problemas de build en iOS

“Error al firmar Code”

Síntomas:

• El build falla durante la fase de firma de code
• Errores de Xcode con certificados o provisioning profiles

Soluciones:

1. Verifica que el certificado sea del tipo de build

   • Los builds de Development requieren certificados de Development
   • Los builds de App Store requieren certificados de Distribution

2. Comprueba que el certificado y el perfil coincidan

   # 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. Asegúrate de que el provisioning profile sea válido

   • Revisa la fecha de expiración
   • Verifica que incluya tu App ID
   • Confirma que incluye el certificado

4. Regenerar credenciales

   • Eliminar certificado/perfil antiguo
   • Crear nuevos en el portal de Apple Developer
   • Recodificar y actualizar las variables de entorno

“El provisioning profile no incluye el certificado de firma”

Síntomas:

• Xcode no encuentra el certificado en el perfil

Soluciones:

1. Descargar el último perfil de Apple

   • Ve a Apple Developer → Certificates, IDs & Profiles
   • Descargar el provisioning profile
   • Asegúrate de que incluya tu certificado

2. Verifica que el certificado esté en el perfil

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

3. Recrea el perfil con el certificado correcto

   • En el portal de Apple Developer, edita el perfil
   • Asegúrate de que tu distribution certificate esté seleccionado
   • Descargar y recodificar

“Error de autenticación en App Store Connect”

Síntomas:

• Error al subir a TestFlight
• Errores de clave API

Soluciones:

1. Verifica las credenciales de la clave API

   • Revisa APPLE_KEY_ID (debe tener 10 caracteres)
   • Revisa APPLE_ISSUER_ID (debe estar en formato UUID)
   • Verifica que APPLE_KEY_CONTENT esté codificado correctamente en base64

2. Sincroniza la hora de tu equipo

   • La autenticación de App Store Connect usa JWT de corta duración generados con la hora local de tu sistema
   • Apple rechaza tokens que caducan más de 20 minutos en el futuro, por lo que incluso una pequeña desviación de reloj puede hacer que una clave válida falle
   • En Windows, abre Configuración > Hora e idioma > Fecha y hora y haz clic en Sync now
   • En macOS, abre Ajustes del Sistema > General > Fecha y hora y activa la hora automática
   • En Linux, comprueba timedatectl status y activa NTP si es necesario
   • Tras sincronizar, vuelve a ejecutar el comando de Capgo build o de credenciales

   Ver los de Apple Generación de tokens para solicitudes de API para conocer la regla de duración de tokens de App Store Connect.

3. Probar la clave API localmente

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

4. Revisa los permisos de la clave API

   • La clave requiere el rol “Developer” o superior
   • Verifica en App Store Connect -> Usuarios y acceso -> Claves

5. Asegúrate de que la clave no esté revocada

   • Compruébalo en App Store Connect
   • Genera una nueva clave si es necesario

La app falla al iniciar en iOS 27

Síntomas:

• La app compilada con Xcode 27 se cierra de inmediato en iOS 27 (TestFlight o dispositivo)
• El informe de fallos muestra _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Solución: las apps creadas con el SDK de iOS 27 deben adoptar el ciclo de vida UIScene. Añade un SceneDelegate y un UIApplicationSceneManifest a ios/App/App/Info.plist, o compila con --xcode-version 26. Capgo ahora bloquea estas builds antes de que empiecen (verificación prescan ios/plist-scene-lifecycle-xcode27).

“Error al ejecutar pod install”

Precaución

Capgo Build dejará de compilar proyectos de CocoaPods en diciembre de 2026. Migra a Swift Package Manager: consulta el Guía de Capacitor SPM.

Síntomas:

• El build falla al instalar CocoaPods
• Errores en el Podfile

Soluciones:

1. Verifica que Podfile.lock esté commiteado

   git status ios/App/Podfile.lock

2. Prueba pod install localmente

   cd ios/App
   pod install

3. Busca pods incompatibles

   • Revisa el Podfile por conflictos de versión
   • Asegúrate de que los pods soporten tu iOS deployment target

4. Limpia el caché de pods

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

Problemas de build en Android

“Contraseña de Keystore incorrecta”

Síntomas:

• El build falla durante el signing
• Errores de Gradle relacionados con el keystore

Soluciones:

1. Verificar la contraseña del keystore

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

2. Revisar las variables de entorno

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

3. Verificar la codificación base64

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

“No se encontró el alias de la clave”

Síntomas:

• El firmado falla con un error de alias

Soluciones:

1. Listar los alias del keystore

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

2. Verificar que el alias coincida exactamente

   • El alias distingue entre mayúsculas y minúsculas
   • Revisar errores tipográficos en KEYSTORE_KEY_ALIAS

3. Usar el alias correcto del keystore

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

“Error en el build de Gradle”

Síntomas:

• Errores genéricos de Gradle
• Problemas de compilación o dependencias

Soluciones:

1. Prueba la compilación localmente primero

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Revisa las dependencias faltantes

   • Revisa los archivos build.gradle
   • Asegúrate de que todos los plugins estén listados en dependencies

3. Verificar compatibilidad de la versión de Gradle

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

4. Limpia la caché de Gradle

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

“Error al subir a la Play Store”

Síntomas:

• El build tiene éxito pero la subida falla
• Errores de cuenta de servicio

Soluciones:

1. Verificar el JSON de la cuenta de servicio

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

2. Comprobar permisos de la cuenta de servicio

   • Ir a Play Console → Configuración → Acceso a la API
   • Asegurar que la cuenta de servicio tenga acceso a tu app
   • Otorgar el permiso “Publicar en pistas de prueba”

3. Verificar que la app esté configurada en Play Console

   • Primero debes crear la app en Play Console
   • Debes subir al menos un APK manualmente al inicio

4. Comprobar que API esté habilitada

   • La API de Google Play Developer debe estar habilitada
   • Verificar en Google Cloud Console

Problemas generales

“Job not found” o “Build status unavailable”

Síntomas:

• No se puede verificar el estado del build
• Errores de Job ID

Soluciones:

1. Espera un momento e inténtalo de nuevo

   • Los trabajos de build pueden tardar unos segundos en inicializarse

2. Comprueba que el ID del trabajo es correcto

   • Verifica el ID del job en la respuesta inicial del build

3. Comprueba que el build no haya expirado

   • Los datos del build están disponibles durante 24 horas

“Error al sincronizar el proyecto”

Síntomas:

• El build falla antes de iniciar la compilación
• Errores por archivos faltantes

Soluciones:

1. Ejecuta Capacitor sync localmente

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Busca archivos nativos ignorados por git

   • Revisa el .gitignore
   • Asegura que no se ignoren archivos de config importantes

El build se completó pero no veo el output

Síntomas:

• Build exitoso pero sin link de descarga

Soluciones:

1. Revisa la configuración del build

   • Artifact storage may not be configured
   • Contacta con soporte si no tienes acceso a los artefactos de tu build

2. Para el envío a TestFlight de iOS

   • Revisa App Store Connect
   • El procesamiento puede tardar de 5 a 30 minutos tras el upload

3. Para Android Play Store

   • Revisa Play Console → Testing → Internal testing
   • El procesamiento puede tardar unos minutos

El build fue exitoso pero el artifact es incorrecto tras cambiar de entorno

Síntomas:

• El estado del build es success pero el IPA/AAB/APK no coincide con la rama o el flavor que acabas de compilar
• AAB de Android ausente o incorrecto tras cambiar credenciales de RC vs producción o --android-flavor
• El build termina sospechosamente rápido tras cambiar la config de firma o el product flavor

Causa: Capgo restaura el caché de build por app por defecto (omite cache_key para la caché general compartida). Si RC y producción comparten el mismo app ID sin claves separadas, una restauración puede reutilizar la salida compilada del entorno anterior.

Soluciones:

1. Usa una clave de caché por entorno (recomendado para pipelines RC/PROD continuos):

   # 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. Forzar un build limpio al depurar:

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

3. En API o integraciones de webhook, pasa cache_key (por ejemplo "prod") o establecer cache_enabled: false para una sola ejecución limpia.

Ver Caché de build para la referencia completa de opciones.

Problemas específicos de CI/CD

Acciones de GitHub: “Command not found”

Síntomas:

• bunx @capgo/cli@latest … falla en CI con “command not found”

Soluciones:

1. Configura Bun primero para que bunx está disponible:

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

2. Luego ejecuta el CLI — bunx lo descarga bajo demanda, sin instalación global:

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

Acciones de GitHub: “Secrets not found”

Síntomas:

• Variables de entorno vacías en el build

Soluciones:

1. Verifica que los secrets estén configurados

   • Ve a Settings del repo → Secrets and variables → Actions
   • Añade todos los secrets necesarios

2. Usa la sintaxis correcta

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

3. Comprueba que los nombres de secretos coincidan

   • Los nombres distinguen entre mayúsculas y minúsculas
   • Sin errores tipográficos en las referencias de secretos

Obtener más ayuda

Activar logs detallados

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

Recopilar información del build

Al contactar con soporte, incluye:

1. Comando de build utilizado

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

2. Mensaje de error (salida completa)

3. ID del job (de la salida de build)

4. Logs de build (copia la salida completa de la terminal)

5. Información del entorno

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

Contactar con soporte

• Discord: Únete a nuestra comunidad
• Email: support@capgo.app
• Documentación: Capgo Docs

Limitaciones conocidas

Limitaciones actuales:

• Tiempo máximo de build: 10 minutos
• Tamaño máximo de upload: ~500MB
• Los builds de iOS requieren alquileres de Mac de 24 horas; los builds en Mac se encolan para garantizar un uso óptimo
• La disponibilidad de la descarga del artefacto de build depende del destino del build y la configuración de almacenamiento de artefactos

Estas limitaciones pueden ajustarse según el feedback.

Prescan bloqueó mi build

Capgo ejecuta un prescan antes del upload. Corrige el hallazgo reportado o ignora solo ese id de check:

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

Consulta el catálogo completo: Checks de prescan.

Recursos adicionales

• Primeros pasos - Guía de configuración inicial
• Opciones de configuración - Flags de CLI, incluyendo --cache-key y --no-cache
• Builds de iOS - Configuración específica para iOS
• Builds de Android - Configuración específica para Android
• Checks de prescan - Lista completa de checks previos al build y flags de ignorado
• Referencia de CLI - Documentación completa de comandos