Problemas de Actualización Comunes

Cuando una comprobación de actualización falla, Capgo suele devolver un error code y un message en el /updates respuesta. Esta página explica las fallas más comunes y las soluciones más rápidas.

Lee esto primero

• no_new_version_available es un estado normal, no un fracaso.
• Muchos informes de “actualizaciones encontradas pero no aplicadas” son rechazos de política/configuración en lugar de retraso en caché, especialmente cuando la respuesta incluye una explicación explícita error code
• Usar npx @capgo/cli@latest app debug mientras se reproduce el problema para ver detalles de solicitud/respuesta.

Códigos de falla comunes

provider_infrastructure_request_blocked

Causa

La aplicación tiene Bloquear solicitudes de infraestructura del proveedor enabled and the request originated from a known Google or Apple datacenter IP range. Capgo blocks these requests on /updates, /stats__CAPGO_KEEP_0__ bloquea estas solicitudes en /channel_self y

para evitar que el tráfico originado por el proveedor se trate como tráfico de dispositivo.

• Solución
• Reproducir la actualización desde un dispositivo físico en una red de usuario normal.
• No utilice sondas alojadas en la nube o ejecutores de centros de datos de proveedor para actualizaciones, estadísticas o comprobaciones de canal-self mientras que esta protección está habilitada. Si ese tráfico es intencional, abra la pestaña Información y desactiveBloquear solicitudes de infraestructura del proveedor",". Rehabilite cuando la prueba esté completa.

Nuevas aplicaciones tienen esta protección habilitada por defecto. Las aplicaciones creadas antes de que se introdujera la configuración mantienen deshabilitada hasta que la habilites.

Detalles de respuesta

• /updates preserva el contrato de respuesta del actualizador y devuelve HTTP 200Su cuerpo incluye error, message, kind: "blocked"o provider ("google" y "apple").
• /stats devuelve HTTP /channel_self con el mismo error __CAPGO_KEEP_0__. Trátalo como una política de bloqueo intencional, no como una condición de retry transitorio. 429 with the same error code. Treat this as an intentional policy block, not a transient retry condition.

disable_auto_update_to_major

Su canal bloquea las actualizaciones principales (

Su canal bloquea las actualizaciones principales (disable_auto_update = majory el número mayor del paquete objetivo está por encima de la versión de línea base del dispositivo.

Síntoma típico

version: 1.0.8 con old: 0.0.0 significa que el dispositivo informa sobre la línea base 0.0.0, por lo que las actualizaciones mayores son rechazadas.

Cómo interpretarlo

El backend compara las versiones mayores utilizando la línea base del dispositivo old y objetivo version.

• Si el objetivo es 1.0.1, la línea base mayor debe ser 1 (por ejemplo 1.0.0).
• Si el objetivo es 10.0.1línea base principal debe ser 10 (por ejemplo 10.0.0).

Opción A de corrección (recomendada): alinear la línea base principal del dispositivo

Establecer plugins.CapacitorUpdater.version en capacitor.config.* así que MAJOR coincida con el MAJOR del paquete que deseas entregar (por ejemplo 1.0.0 para 1.0.1, 10.0.0 para 10.0.1).

Luego aplique esta configuración a la aplicación instalada una vez:

1. Ejecutar npx cap sync.
2. Reconstruye y reinstala la aplicación nativa.

Solución B: relaja la política del canal

Permite actualizaciones automáticas entre versiones mayores en los ajustes del canal (solo si esa estrategia de lanzamiento es intencional).

Documentación relacionada:

• Versiones objetivo: Desactiva la actualización automática entre versiones mayores
• Canales: Desactiva las estrategias de actualización automática

disable_auto_update_to_minor / disable_auto_update_to_patch

Causa

La política del canal es más estricta (o) que la actualización ofrecida.minor obstruye cuando el paquete objetivo tiene un número mayor o menor que la versión nativa del dispositivo ( patcho

• minor )version_buildEjemplo: 1.2.3 -> 1.3.0 está bloqueado.
• patch bloquea cualquier cambio de número mayor, menor o de parche desde version_buildSólo se permiten cambios de sufijo mientras MAJOR.MINOR.PATCH se mantiene idéntico, como 1.0.0-beta.1 -> 1.0.0-beta.2 o 1.0.0+build.1 -> 1.0.0+build.2.

Corrección

• Cargar un conjunto de paquetes compatible con la política actual, o
• cambiar la política de canal en dashboard/CLI.

Documentación relacionada:

• Canales: Deshabilitar estrategias de actualización automática

disable_auto_update_to_metadata

Por causa de

El canal utiliza la segmentación basada en metadatos (version_number) y la base de dispositivo está por debajo de lo requerido min_update_version.

Solución

• Alinea la base de dispositivo (CapacitorUpdater.version) con la versión nativa de la aplicación instalada, o
• ajusta min_update_version la estrategia del canal.

Documentación relacionada:

• Canales: Deshabilitar estrategias de actualización automática

disable_auto_update_under_native

Por causa de

Evita que el canal se degrade por debajo de la base nativa.

Solución

• Sube una versión de paquete mayor o igual a la base nativa, o
• desactiva la protección contra degradaciones ‘bajo la base nativa’ para ese canal.

Documentación relacionada:

• Objetivo de versión: Prevención de degradaciones automáticas

cannot_update_via_private_channel

Causa

El canal seleccionado/por defecto no permite la asignación de dispositivo por parte del dispositivo.

Solución

• Usa un canal diferente con la asignación de dispositivo habilitada, o
• haz que el canal sea público / habilita la asignación de dispositivo.

Documentos relacionados:

• Canales: Usando setChannel() desde tu aplicación

unknown_version_build / semver_error

Causa

La versión base del dispositivo está faltando (unknown) o no es un semver válido.

Solución

• Establecer plugins.CapacitorUpdater.version a un semver válido como 1.2.3.
• Sync and rebuild native app.

Documentos relacionados:

• Canales: Versión de paquete y canales
• Solución de problemas: Actualizaciones no se aplican

unsupported_plugin_version

Causa

La versión del plugin de actualizador es demasiado antigua para los requisitos actuales del backend.

Solución

• Actualizar @capgo/capacitor-updater.
• Ejecutar npx cap sync.
• Reconstruya y reinstale la aplicación nativa.

disabled_platform_ios / disabled_platform_android

La causa

El canal tiene actualizaciones deshabilitadas para esa plataforma.

Solución

• Habilite el botón de plataforma en el canal.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

La causa

El canal no permite el tipo de compilación actual o el objetivo de tiempo de ejecución.

Solución

• Alinee las opciones del canal (allow_prod, allow_dev, allow_device, allow_emulator) con su objetivo de prueba.

key_id_mismatch

La causa

La clave de cifrado del paquete y la clave del dispositivo difieren.

Solución

• Utilice la misma clave de cifrado/clave pública en la configuración de la aplicación y en el flujo de cifrado del paquete.

no_channel / null_channel_data

Causa

No se resolvió un canal válido para el dispositivo.

Solución

• Establezca un canal predeterminado en la nube, o
• establezca defaultChannel en compilaciones de prueba, o
• asigne una sobrescritura de canal para el dispositivo.

Documentación relacionada:

• Canales

on_premise_app

Causa

El backend devolvió HTTP 429 con on_premise_appEsto ocurre en tres situaciones:

1. El ID de la aplicación no existe en Capgo — el app_id El ID de la aplicación enviado por el dispositivo no está registrado, por lo que el backend no tiene registro de él.
2. La aplicación está marcada como en sitio — la aplicación existe pero está configurada para actualizaciones autoadministradas, por lo que el punto de conexión de la nube Capgo se niega a servirla.
3. El plan de la organización ha sido cancelado — la organización de la aplicación ya no tiene una suscripción activa.

Error común

Un error de ortografía en plugins.CapacitorUpdater.appId (en capacitor.config.ts) o una incompatibilidad con el ID de la aplicación registrada en la consola de Capgo. El servidor no puede distinguir entre ‘aplicación desconocida’ y ‘aplicación en el lugar’, por lo que devuelve el mismo error code.

Solución

• Verificar que app_id coincida exactamente con lo que se muestra en la consola de Capgo (sensible a mayúsculas y minúsculas).
• Si la aplicación no está registrada aún, ejecutar npx @capgo/cli@latest app add.
• Si la aplicación está configurada para estar en el lugar, establecer plugins.CapacitorUpdater.updateUrl su propio punto de actualización en lugar de la URL de nube de Capgo.
• Si el plan de la organización ha expirado, renueva o actualiza el plan.

Lista de verificación rápida de diagnóstico

1. Confirme que el ID de la aplicación y el canal están correctos para la compilación.
2. Confirmar CapacitorUpdater.version Coincide con la versión nativa de la aplicación instalada.
3. Confirmar la política del canal (disable_auto_update) coincide con la implementación prevista.
4. Confirmar que los interruptores de plataforma/compilación permiten este dispositivo.
5. Ejecutar npx @capgo/cli@latest app debug y leer el error de servidor de backend code.

¿Necesita más ayuda?

• Solución de problemas
• How to obtener soporte

Sigue adelante desde Problemas de Actualización Comunes

Si estás utilizando Problemas de Actualización Comunes para planificar el trabajo de plugin nativo, conecta con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Capgo Directorio de Plugin para el flujo de trabajo del producto en Capgo Directorio de Plugin, Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise.