Resolución de problemas

Solución a problemas comunes al construir aplicaciones nativas con Capgo Cloud Build.

Fallas de construcción

“Subida fallida” o “Tiempo de conexión agotado”

Síntomas:

• La construcción falla durante la subida del proyecto
• Errores de tiempo después de 60 segundos

Solución:

1. Verifique su conexión a Internet

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

2. Reducir el tamaño del proyecto

   • Asegúrate de que node_modules/ no esté subiendo (debería excluirse automáticamente)
   • Verifica la presencia de archivos grandes en tu proyecto:

   find . -type f -size +10M

3. Verifica la expiración de la URL de subida

   • Las URL de subida caducan después de 1 hora
   • Si obtienes un error de URL caducada, vuelve a ejecutar el comando de compilación

Consejo

Los proyectos muy grandes pueden alcanzar el límite de tiempo de compilación (ver Limitaciones conocidas. Contacte con el soporte para opciones de empresa.

“Tiempo de construcción después de 10 minutos”

Síntomas:

• El tiempo de construcción supera el tiempo máximo permitido
• El estado muestra timeout

Soluciones:

1. Optimizar dependencias

   • Eliminar paquetes npm no utilizados
   • Usar npm prune --production antes de construir

2. Verifique problemas de red en la compilación

   • Algunas dependencias pueden descargar archivos grandes durante la compilación
   • Considerar la caché previa con un archivo de bloqueo

3. Revisar 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 su aplicación necesita legítimamente más tiempo
   • Podemos ajustar límites para casos de uso específicos

Problemas de autenticación

“La clave API es inválida” o “No autorizado”

Síntomas:

• La construcción falla de inmediato con un error de autenticación
• Errores 401 o 403

Solutions:

1. Verifique que la clave API sea correcta

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

2. Verifique los permisos de la clave API

   • La clave debe tener write o all permisos
   • Verifique en el Capgo en la consola de API Claves

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

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

   bunx @capgo/cli@latest login

“No se encontró la aplicación” o “No tiene permiso para esta aplicación”

Síntomas:

• El inicio de sesión funciona pero hay un error específico de la aplicación

Soluciones:

1. Verificar que la aplicación esté registrada

   bunx @capgo/cli@latest app list

2. Comprobar que el ID de la aplicación coincida

   • Verificar capacitor.config.json appId
   • Asegurarse de que el comando utilice el ID de la aplicación correcto

3. Verificar acceso a la organización

   • Comprobar que estás en la organización correcta
   • API debe tener acceso a la organización de la aplicación

Problemas de compilación de iOS

“Code firma fallida”

Síntomas:

• La compilación falla durante la fase de firma de code
• Errores de Xcode sobre certificados o perfiles

Soluciones:

1. Verificar que el tipo de certificado coincida con el tipo de compilación

   • Las compilaciones de desarrollo necesitan certificados de desarrollo
   • Las compilaciones para la tienda de aplicaciones necesitan certificados de distribución

2. Comprobar 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úrese de que el perfil de provisión es válido

   • Verifique la fecha de caducidad
   • Verifique que incluye su ID de aplicación
   • Confirme que incluye el certificado

4. Regenere las credenciales

   • Elimine el certificado/perfil antiguo
   • Crear nuevos en el portal del desarrollador de Apple
   • Re-encode y actualice las variables de entorno

“El perfil de provisión no incluye el certificado de firma”

Síntomas:

• Xcode no puede encontrar el certificado en el perfil

Solutions:

1. Descargar el perfil más reciente de Apple

   • Ir a Apple Developer → Certificados, IDs y Perfiles
   • Descargar perfil de configuración
   • Asegúrate de que incluya tu certificado

2. Verificar 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. Recrear el perfil con el certificado correcto

   • En el portal de Apple Developer, editar perfil
   • Asegúrate de que se haya seleccionado tu certificado de distribución
   • Descargar y re-encodificar

“Autenticación de App Store Connect fallida”

Síntomas:

• La subida a TestFlight falla
• API errores de clave

Soluciones:

1. Verificar credenciales de clave API

   • Comprueba APPLE_KEY_ID (debe ser de 10 caracteres)
   • Comprueba APPLE_ISSUER_ID (debe ser formato UUID)
   • Verifica que APPLE_KEY_CONTENT esté correctamente codificado en base64

2. Sincroniza el reloj de tu computadora

   • La autenticación de App Store Connect utiliza JWTs de corta duración generados a partir del tiempo de tu sistema local
   • Apple rechaza tokens que expiran más de 20 minutos en el futuro, por lo que incluso pequeños desfases de reloj pueden hacer que una clave válida de otro modo fracase
   • En Windows, abre Configuración > Tiempo y idioma > Fecha y hora y haz clic en Sync ahora
   • En macOS, abre Configuración del sistema > General > Fecha y hora y habilita el tiempo automático
   • En Linux, verifica timedatectl status y habilita NTP si es necesario
   • Después de sincronizar, vuelve a ejecutar la Capgo construcción o comando de credenciales

   Consulte la documentación de Apple en Generar tokens para API solicitudes documentación para la regla de vida útil del token de App Store Connect

3. Probar API clave localmente

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

4. Verificar permisos de API clave

   • La clave necesita el rol “Desarrollador” o superior
   • Verificar en App Store Connect -> Usuarios y acceso -> Claves

5. Asegurarse de que la clave no esté revocada

   • Verificar en App Store Connect
   • Generar nueva clave si es necesario

“Falló la instalación de Pods”

Síntomas:

• La compilación falla durante la instalación de CocoaPods
• Errores de Podfile

Soluciones:

1. Verificar que Podfile.lock esté comprometido

   git status ios/App/Podfile.lock

2. Probar la instalación de Pods localmente

   cd ios/App
   pod install

3. Comprobar pods incompatibles

   • Revisar Podfile para conflictos de versión
   • Asegurarse de que todos los pods soporten su destino de implementación iOS

4. Limpiar caché de pods

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

Problemas de compilación de Android

“Contraseña de keystore incorrecta”

Síntomas:

• La compilación falla durante la firma
• Errores de Gradle sobre keystore

Soluciones:

1. Verificar contraseña del keystore

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

2. Comprobar variables de entorno

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

3. Verificar codificación base64

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

“Alias de clave no encontrado”

Síntomas:

• El proceso de firma falla con un error de alias

Soluciones:

1. Listar alias del keystore

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

2. Verificar que el alias coincida exactamente

   • El alias es sensible a mayúsculas y minúsculas
   • Comprobar errores de ortografía 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 de compilación de Gradle”

Síntomas:

• Errores de Gradle generales
• Problemas de compilación o dependencias

Soluciones:

1. Prueba la compilación localmente primero

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Verificar dependencias faltantes

   • Revisar archivos build.gradle
   • Asegurarse de que todas las plugins estén listadas en dependencias

3. Verificar compatibilidad de versión de Gradle

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

4. Limpiar caché de Gradle

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

“Falló el envío a la tienda Play”

Síntomas:

• El proyecto se compila correctamente pero el envío falla
• Errores de cuenta de servicio

Soluciones:

1. Verificar archivo JSON de cuenta de servicio

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

2. Comprobar permisos de cuenta de servicio

   • Ir a Google Play Console → Configuración → API Acceso
   • Asegurarse de que la cuenta de servicio tenga acceso a tu aplicación
   • Otorgar permiso de “Lanzar a pistas de pruebas”

3. Comprobar que la aplicación esté configurada en Google Play Console

   • La aplicación debe haberse creado primero en Google Play Console
   • Al menos un APK debe haberse subido manualmente inicialmente

4. Comprobar que API esté habilitado

   • Debes habilitar el API de desarrollador de Google Play
   • Ver en la Consola de Google Cloud

Problemas Generales

“No se encontró el trabajo” o “Estado de construcción no disponible”

Síntomas:

• No se puede verificar el estado de construcción
• Errores de ID de trabajo

Soluciones:

1. Espera un momento y vuelve a intentarlo

   • Los trabajos de construcción pueden tardar unos segundos en inicializarse

2. Verificar que el ID de trabajo sea correcto

   • Verifique el ID de la tarea desde la respuesta de construcción inicial

3. Compruebe que la construcción no ha expirado

   • Los datos de construcción están disponibles durante 24 horas

“La sincronización del proyecto ha fallado”

Síntomas:

• La construcción falla antes de que comience la compilación
• Errores de archivos faltantes

Solución:

1. Ejecutar Capacitor sincronización local

   bunx cap sync

2. Asegúrese de que todos los archivos nativos estén comprometidos

   git status ios/ android/

3. Buscar archivos nativos ignorados en Git

   • Revisar .gitignore
   • Asegúrese de que los archivos de configuración importantes no estén ignorados

“El compilado tuvo éxito pero no veo salida”

Síntomas:

• El compilado muestra éxito pero no hay enlace de descarga

Soluciones:

1. Verifique la configuración de compilación

   • El almacenamiento de artefactos puede no estar configurado
   • Contacte con el soporte si no tiene acceso a los artefactos para su compilación

2. Para la presentación de iOS en TestFlight

   • Verifique App Store Connect
   • El procesamiento puede tardar entre 5-30 minutos después de la carga

3. Para el almacenamiento de aplicaciones Android

   • Verifique Play Console → Pruebas → Pruebas internas
   • El procesamiento puede tardar unos minutos

La compilación tuvo éxito pero el artefacto está mal después de un cambio de entorno

Síntomas:

• El estado de la compilación es success pero el IPA/AAB/APK no coincide con la rama o sabor que acaba de construir
• Android AAB faltante o incorrecto después de cambiar las credenciales RC vs producción o --android-flavor
• La construcción termina de manera sospechosa rápidamente después de cambiar la configuración de firma o sabor de producto

Causa: Capgo restaura el caché de construcción por aplicación por defecto (omitir cache_key para el caché general compartido). Si RC y producción comparten el mismo ID de aplicación sin claves separadas, una restauración puede reutilizar el código compilado del entorno anterior.

Soluciones:

1. Utilice una clave de caché por entorno (recomendado para flujos de trabajo 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 una compilación limpia cuando se está depurando:

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

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

Consulte Caja de compilación para la referencia completa de la opción.

Problemas específicos de CI/CD

GitHub Acciones: “comando no encontrado”

Síntomas:

• bunx @capgo/cli@latest … falla en CI con “comando no encontrado”

Soluciones:

1. Configura Bun primero entonces bunx está disponible:

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

2. Luego ejecute el CLI — bunx lo obtiene a demanda, no se necesita instalación global:

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

GitHub Acciones: “No se encontraron secretos”

Síntomas:

• Variables de entorno vacías en la compilación

Soluciones:

1. Verifique que los secretos estén configurados

   • Vaya a Configuración de repositorio → Secretos y variables → Acciones
   • Agregue todos los secretos necesarios

2. Utilice la sintaxis correcta

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

3. Verificar que los nombres de secretos coincidan

   • Los nombres son sensibles a mayúsculas y minúsculas
   • No hay errores de ortografía en las referencias a secretos

Obtener más ayuda

Habilitar depuración detallada

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

Recopilar información de compilación

Cuando contacte con el soporte, incluya:

1. Comando de construcción utilizado

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

2. Mensaje de error (salida completa)

3. ID de tarea (de la salida de construcción)

4. Registros de construcción (copiar salida completa del terminal)

5. Información del entorno

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

Contactar con Soporte

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

Limitaciones conocidas

Limitaciones actuales:

• Tiempo máximo de construcción: 10 minutos
• Tamaño máximo de carga: ~500MB
• Los builds de iOS requieren arrendamientos de Mac de 24 horas, construya en Mac para encolar y asegurar el uso óptimo
• La disponibilidad de descarga de artefactos de construcción depende de la configuración de destino de construcción y almacenamiento de artefactos

Estas limitaciones pueden ajustarse según la retroalimentación

Estas limitaciones pueden ajustarse según la retroalimentación

Capgo ejecuta un prescan local prescan antes de la carga. Corrija el hallazgo informado, o ignora solo ese id de verificación:

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

Ver el catálogo completo: Prescan de comprobación.

Recursos adicionales

• Inicio - Guía de configuración inicial
• Opciones de configuración - Bandejas incluyendo CLI --cache-key Compilación para iOS --no-cache
• - Configuración específica de iOS Compilación para Android
• y - Configuración específica de Android
• Verificación de prescaneo - Lista completa de verificaciones de precompilación y banderas de ignorar
• CLI Referencia - Documentación completa de la orden