Solucionar Problemas

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

Errores de construcción

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

Síntomas:

• Falló la compilación durante la subida del proyecto
• 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 estar excluido automáticamente)
   • Verifica archivos grandes en tu proyecto:

   find . -type f -size +10M

3. Verifique 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

Los proyectos muy grandes pueden alcanzar el límite de tiempo de compilación (consulte Limitaciones conocidasContacte con el soporte para opciones de empresas.

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

Síntomas:

• La construcción excede el tiempo máximo permitido
• Estado muestra timeout

Solutions:

1. Optimizar dependencias

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

2. Comprobar problemas de red en 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 al soporte

   • Si su aplicación necesita legítimamente más tiempo
   • Podemos ajustar los límites para casos de uso específicos

Problemas de autenticación

”API key invalid” or “Unauthorized”

Síntomas:

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

Soluciones:

1. Verificar que 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 permisos
   • Verificar en el panel de control de Capgo bajo Claves API

3. Asegurarse de que la clave API esté siendo leída

   # 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

"App no encontrado" 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. Verifica que la aplicación esté registrada

   bunx @capgo/cli@latest app list

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

   • Verificar capacitor.config.json appId
   • Verifique que el comando utiliza la ID de aplicación correcta

3. Verificar acceso a la organización

   • Compruebe que se encuentra en la organización correcta
   • La clave API debe tener acceso a la organización de la aplicación

Problemas de compilación de iOS

“La firma de Code falló”

Síntomas:

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

Solución:

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

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

2. Compruebe que el certificado y el perfil coinciden

   # 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

   • Compruebe la fecha de vencimiento
   • Verifique que incluya su ID de App
   • Confirme que incluye el certificado

4. Regenerar credenciales

   • Eliminar certificado/perfil antiguo
   • Crear nuevos en el portal de desarrolladores de Apple
   • Re-encode 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

Solutions:

1. Descargar el perfil más reciente de Apple

   • Ir a Desarrolladores de Apple → Certificados, IDs y Perfiles
   • Descargar 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 perfil con certificado correcto

   • En el portal de desarrolladores de Apple, 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:

• La subida a TestFlight falla
• Errores en la clave API

Soluciones:

1. Verificar credenciales de clave API

   • Comprueba APPLE_KEY_ID (debe ser 10 caracteres)
   • Comprueba APPLE_ISSUER_ID (debe ser formato UUID)
   • Verificar 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 Sincronizar ahora
   • En macOS, abre Configuración del sistema > General > Fecha y hora y habilite la sincronización de hora automática
   • En Linux, compruebe timedatectl status y habilite NTP si es necesario
   • Después de sincronizar, ejecute nuevamente la orden de compilación o credenciales Capgo

   Consulte la documentación de Apple para Generar 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 necesita el rol de "Desarrollador" o superior
   • Verificar en App Store Connect -> Usuarios y Acceso -> Claves

5. Asegurarse de que la clave no esté revocada

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

”Falló la instalación de Pods”

Síntomas:

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

Soluciones:

1. Verificar que Podfile.lock esté comprometido

   git status ios/App/Podfile.lock

2. Instalar test de pod localmente

   cd ios/App
   pod install

3. Buscar pods incompatibles

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

4. Borrar 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 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

”Key alias not found”

Síntomas:

• Falla al firmar con error de alias

Soluciones:

1. Listar alias del keystore

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

2. Verifique que el alias coincida exactamente

   • El alias es sensible a mayúsculas y minúsculas
   • Revisar 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 genericos
• 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 dependencias

3. Verifica la compatibilidad de la versión de Gradle

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

4. Borra la caché de Gradle

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

”Subida a la Tienda de Juegos fallida”

Síntomas:

• La compilación tiene éxito pero la subida falla
• Errores de cuenta de servicio

Solutions:

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 la Consola de Juegos → Configuración → API Acceso
   • Asegurarse de que la cuenta de servicio tenga acceso a tu aplicación
   • Conceda permiso para la puesta en producción de ‘Rutas de prueba’

3. Verifique que la aplicación esté configurada en el Console de Play

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

4. Verifique que API está habilitado

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

Problemas Generales

‘No se encontró trabajo’ o ‘Estado de construcción no disponible’

Simptomas:

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

Solutions:

1. Espera un momento y vuelve a intentarlo

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

2. Verifica que el ID de trabajo sea correcto

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

3. Verifica que la construcción no ha expirado

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

”Falló la sincronización del proyecto”

Síntomas:

• Los errores de compilación comienzan antes de que comience la compilación
• Errores de archivos faltantes

Solutions:

1. Ejecuta Capacitor sincronizado localmente

   bunx cap sync

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

   git status ios/ android/

3. Verifica archivos nativos ignorados en Git

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

”Construcción exitosa pero no veo salida”

Síntomas:

• La construcción muestra éxito pero no hay enlace de descarga

Solutions:

1. Verificar la configuración de la construcción

   • El almacenamiento de artefactos puede no estar configurado
   • Contactar con soporte si el acceso a los artefactos está inaccesible para tu construcción

2. Para la presentación de pruebas de iOS en TestFlight

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

3. Para Android Play Store

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

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 ejecuta 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 compilación

Soluciones:

1. Verificar que los secretos estén configurados

   • Ir a configuración de repo → Secretos y variables → Acciones
   • Agregar todos los secretos necesarios

2. Use syntax correctly

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

3. Comprobar que los nombres de secretos coinciden

   • 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)
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 (de salida de compilación)

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

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: 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 la retroalimentación.

Recursos Adicionales

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