Solucionar problemas

Soluciones a problemas comunes al crear aplicaciones nativas con Capgo Cloud Build.

Fracaso en la construcción

”Falló la subida” o “Tiempo de conexión agotado”

Síntomas:

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

Soluciones:

1. Verifica tu 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 se esté subiendo (debería excluirse automáticamente)
   • Verifica archivos grandes en tu proyecto:

   find . -type f -size +10M

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

   • Las URLs de carga caducan después de 1 hora
   • Si obtiene un error de URL caducada, ejecute nuevamente el comando de compilación

Consejo

Los proyectos grandes (>200MB) pueden superar los límites de tiempo. Contacte con soporte para opciones de empresa

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

La construcción supera el tiempo máximo permitido

• El estado muestra
• Soluciones: timeout

Optimice dependencias

1. Síntomas: La construcción supera el tiempo máximo permitido

   • Elimine paquetes npm no utilizados
   • Utilice npm prune --production antes de construir

2. Verifique problemas de red durante la construcción

   • Algunas dependencias pueden descargar archivos grandes durante la construcció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 compilación falla de inmediato con error de autenticación
• errores 401 o 403

Soluciones:

1. Verificar que la clave API es correcta

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

2. Verificar permisos de la clave API

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

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

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or verify local .capgo file
   cat .capgo

4. Reautenticar

   npx @capgo/cli@latest login

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

Síntomas:

• La autenticación funciona pero hay un error específico del aplicación

Soluciones:

1. Verificar que la aplicación esté registrada

   npx @capgo/cli@latest app list

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

   • Verificar capacitor.config.json appId
   • Asegurarse de que el comando utiliza 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 falló la firma”

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. Verificar 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. Asegurarse de que el perfil de provisión sea válido

   • Verificar la fecha de vencimiento
   • Comprobar que incluya su ID de aplicación
   • Confirmar que incluya el certificado

4. Regenerar credenciales

   • Eliminar el certificado/perfil antiguo
   • Crear nuevos en el portal del desarrollador de Apple
   • Re-encodificar y actualizar 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

Soluciones:

1. Descargar el perfil más reciente de Apple

   • Ir a Desarrollador de Apple → Certificados, IDs y Perfiles
   • Descargar perfil de configuración
   • Asegurarse de que incluya su 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 desarrolladores de Apple, edite su perfil
   • Asegúrese de que su certificado de distribución esté seleccionado
   • Descargue y vuelva a codificar

”App Store Connect authentication failed”

Síntomas:

• La carga a TestFlight falla
• Errores de clave API

Soluciones:

1. Verifique las credenciales de la clave API

   • Verifique APPLE_KEY_ID (debe ser de 10 caracteres)
   • Verifique APPLE_ISSUER_ID (debe ser en formato UUID)
   • Verificar que APPLE_KEY_CONTENT está correctamente codificado en base64

2. Probar la clave API localmente

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

3. Comprobar permisos de la clave API

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

4. Asegurarse de que la clave no esté revocada

   • Comprobar en App Store Connect
   • Generar una nueva clave si es necesario

Sección titulada “”Pod install failed””

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. Buscar pods incompatibles

   • Revisar Podfile para conflictos de versiones
   • Asegúrese de que todos los pods soporten su destino de compilación de 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

”Keystore password incorrect”

Síntomas:

• La compilación falla durante la firma
• Errores de Gradle sobre el 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

”Key alias not found”

Síntomas:

• Falla al firmar con error de alias

Soluciones:

1. Lista de 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
   • Revisa errores de tecleo en KEYSTORE_KEY_ALIAS

3. Utiliza 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 la 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

”Play Store upload failed”

Síntomas:

• La compilación tiene éxito pero la subida 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 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. Verificar si la aplicación está configurada en Play Console

   • La aplicación debe haberse creado primero en Play Console
   • Se debe subir al menos un APK manualmente inicialmente

4. Comprobar que API está habilitado

   • El acceso de Google Play Developer API debe estar habilitado
   • Comprobar en Google Cloud Console

Problemas Generales

"Trabajo no encontrado" o "Estado de compilación no disponible"

Síntomas:

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

Soluciones:

1. Espere un momento y vuelva a intentarlo

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

2. Verifica que el ID de trabajo sea correcto

   • Verificar el ID de trabajo desde la respuesta de la construcción inicial

3. Verifique que la construcción no ha expirado

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

”Project sync failed”

Síntomas:

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

Soluciones:

1. Ejecute Capacitor sincronización localmente

   npx cap sync

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

   git status ios/ android/

3. Comprobar archivos nativos ignorados por Git

   • Revisar .gitignore
   • Asegurarse de que los archivos de configuración importantes no se ignoran

”Build succeeded but I don’t see output”

Síntomas:

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

Soluciones:

1. Comprobar la configuración del build

   • El almacenamiento de artefactos puede no estar configurado
   • Contacte al soporte si no se puede acceder a los artefactos para su compilación

2. Para la presentación de iOS en TestFlight

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

3. Para Android Play Store

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

Problemas específicos de CI/CD

GitHub Acciones: “Comando no encontrado”

Síntomas:

• npx @capgo/cli falla en CI

Soluciones:

1. Asegúrese de que esté instalado Node.js

   - uses: actions/setup-node@v6
     with:
       node-version: '24'

2. Instale CLI de manera explícita

   - run: npm install -g @capgo/cli

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

   • Ir a la configuración del repositorio → Secretos y variables → Acciones
   • Agregar todos los secretos requeridos

2. Usar la sintaxis correcta

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

3. Comprobar que los nombres de los 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 registro detallado

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

Recopilar información de compilación

Al contactar con soporte, incluya:

1. Comando de compilación utilizado

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

2. Mensaje de error (salida completa)

3. ID de trabajo (de salida de compilación)

4. Registros de compilación (copiar toda la salida del terminal)

5. Información del entorno

   node --version
   npm --version
   npx @capgo/cli --version

Contactar con Soporte

• Discord: Únete a nuestra comunidad
• Correo electrónico: soporte@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 un 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 las retroalimentaciones

Recursos adicionales

• Iniciar Guía de configuración inicial
• Compilación de iOS - Configuración específica de iOS
• Compilación de Android - Configuración específica de Android
• CLI Referencia - Documentación completa del comando