Solución de Problemas

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

Fallas de construcción

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

Síntomas:

• El proyecto falla durante la carga
• Errores de tiempo después de 60 segundos

Solución:

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 node_modules/ no esté siendo subido (debería excluirse automáticamente)
   • Verifica archivos grandes en tu proyecto:

   find . -type f -size +10M

3. Ver la expiración de la URL de carga

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

Consejo

Very large projects may hit the build-time limit (see Limitaciones conocidasContacte con el soporte para opciones de empresa.

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

Síntomas:

• Build exceeds maximum allowed time
• El estado muestra timeout

Soluciones:

1. Optimizar dependencias

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

2. Verifique problemas de red en la compilació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 al soporte

   • If your app necesita legítimamente más tiempo
   • Puedemos ajustar los límites para casos de uso específicos

Problemas de autenticación

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

Síntomas:

• La compilación falla inmediatamente con un error de autenticación
• Errores 401 o 403

Soluciones:

1. Verifique la clave API es correcta

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

2. Verificar permisos de la clave API

   • La clave debe tener write o all permissions
   • Check in Capgo dashboard under API Keys

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. Verificar permisos

   bunx @capgo/cli@latest login

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

Síntomas:

• Autenticación funciona pero hay errores específicos del app

Soluciones:

1. Verificar que la aplicación esté registrada

   bunx @capgo/cli@latest app list

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

   • Verificar capacitor.config.json appId
   • Ensure command uses correct app ID

3. Verifique el acceso a la organización

   • Verifique que se encuentra 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ó el proceso de firma”

Síntomas:

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

Soluciónes:

1. Verify certificate type matches build type

   • Los builds de desarrollo necesitan certificados de desarrollo
   • Los builds de App Store necesitan certificados de distribución

2. Verifique 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 vencimiento
   • Verifique que incluya su ID de aplicación
   • Confirme que incluye el certificado

4. Regenerar credenciales

   • Eliminar certificado/perfil antiguo
   • Crear nuevos en el portal de desarrolladores de Apple
   • Re-encodificar y actualizar variables de entorno

El perfil de provisión no incluye 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 Desarrolladores de Apple → Certificados, IDs y Perfiles
   • Descargar el perfil de provisió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 Apple Developer, editar perfil
   • Asegurarse de que el certificado de distribución esté seleccionado
   • Descargar y re-encodificar

“Falló la autenticación de App Store Connect”

Síntomas:

• Falló la subida a TestFlight
• API errores de clave

Soluciónes:

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)
   • Verifique que APPLE_KEY_CONTENT esté correctamente codificado en base64

2. Sincronice el reloj de su computadora

   • La autenticación de App Store Connect utiliza JWT de vida corta generados a partir del tiempo de sistema local
   • Apple rechaza tokens que expiran más de 20 minutos en el futuro, por lo que incluso pequeños desfases horarios pueden hacer que una clave válida de otro modo fracase.
   • En Windows, abra Ajustes > Tiempo y idioma > Fecha y hora y haga clic en Sync ahora
   • On macOS, abra Configuración del sistema > General > Fecha y hora y habilite la sincronización automática de hora
   • On Linux, verifique timedatectl status y habilite NTP si es necesario
   • Después de sincronizar, ejecute de nuevo la Capgo construcción o comando de credenciales

   Ver Apple’s Generación de tokens para solicitudes de API la regla de duración del token de App Store Connect

3. Pruebe la clave API localmente

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

4. Verifique los permisos de la clave API

   • La clave requiere el rol 'Desarrollador' o superior
   • Verifique en App Store Connect -> Usuarios y Acceso -> Claves

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

   • Verifique en App Store Connect
   • Genere una nueva clave si es necesario

“Falló la instalación de Pod”

Síntomas:

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

Soluciones:

1. Verifique 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 versión
   • Asegúrese de que todos los pods soporten su destino de despliegue 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

“La contraseña del keystore es incorrecta”

Síntomas:

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

• 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 los errores de ortografía en KEYSTORE_KEY_ALIAS

3. Utilice el alias correcto del keystore

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

“Falló la 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. Comprueba las dependencias faltantes

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

3. Verificar compatibilidad de la versión de Gradle

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

4. Borra el caché de Gradle

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

Fallo al subir a Play Store

Síntomas:

• El build tiene éxito pero el envío falla
• Errores de cuenta de servicio

Soluciones:

1. Verificar 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 la consola de Play → Configuración → API Acceso
   • Asegúrese de que la cuenta de servicio tenga acceso a su aplicación
   • Otorgue permiso de “Lanzamiento a pistas de prueba”

3. Verify app is set up in Play Console

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

4. Verifique que API esté habilitado

   • El API de Desarrollador de Google Play debe estar habilitado
   • Verifique en el Console de Cloud de Google

Problemas Generales

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

Síntomas:

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

Solución:

1. Espere un momento y vuelva a intentarlo

   • Build jobs may take a few seconds to initialize

2. Verifique que el ID de trabajo sea correcto

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

3. Verifique que la construcción no ha expirado

   • Build data is available for 24 hours

“La sincronización del proyecto ha fallado”

Síntomas:

• La compilación falla antes de comenzar
• Errores de archivos faltantes

Soluciones:

1. Ejecutar Capacitor sincronizado localmente

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Comprobar archivos nativos ignorados en Git

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

“El build tuvo éxito pero no veo la salida”

Síntomas:

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

Solución:

1. Verifique la configuración del build

   • Almacenamiento de artefactos no está configurado
   • Contacta al soporte si no tienes acceso a los artefactos de tu build

2. Para la presentación de iOS en TestFlight

   • Para la presentación de iOS en TestFlight
   • Processing may take 5-30 minutes after upload

3. Para Android Store de Google

   • Verifica la consola de Play → Pruebas → Pruebas internas
   • El proceso puede tardar unos minutos

La compilación tuvo éxito pero el artefacto está mal después de cambiar 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 acabas de compilar
• Android AAB faltó o está incorrecto después de cambiar credenciales de RC vs producción --android-flavor
• La compilación termina de manera sospechosa justo después de cambiar la configuración de firma o el sabor del producto

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

Soluciones:

1. Usar una clave de cache 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 al depurar:

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

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

Consulte Build cache para la referencia completa de opciones.

Problemas específicos de CI/CD

GitHub Acciones: “No se encontró el comando”

Síntomas:

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

Solución:

1. Configura Bun primero entonces bunx está disponible:

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

2. Luego ejecuta el CLI — bunx lo descarga según sea necesario, no necesita instalación global:

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

GitHub Acciones: “Secretos no encontrados”

Síntomas:

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

Solución:

1. Verificar que los secretos estén configurados

   • Ir a 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. Verifique que los nombres de secretos coincidan

   • Los nombres son sensibles a la casilla
   • No errores en referencias secretas

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

Al contactar con soporte, incluya:

1. Comando de compilación utilizado

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

2. Mensaje de error (salida completa)

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

4. Build logs (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
• Email: support@capgo.app
• Documentación: Capgo Documentos

Limitaciones conocidas

Limitaciones actuales:

• Tiempo máximo de construcción: 10 minutos
• Tamaño máximo de carga: ~500MB
• iOS requiere arrendamientos de Mac de 24 horas, construir en Mac encolará para garantizar 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 comentarios del usuario

Prescan bloqueó mi construcción

Capgo ejecuta una prescan local prescan antes de subir. 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 verifica.

Recursos adicionales

• Inicio rápido - Guía de configuración inicial
• Opciones de configuración - Bandejas de CLI incluyendo --cache-key y --no-cache
• Compilación de iOS - Configuración específica de iOS
• Compilaciones de Android - Configuración específica de Android
• Verificaciones de prescaneo - Lista completa de verificaciones precompilación e ignorar banderas
• CLI Referencia - Documentación de comando completo