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 mensaje de 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 una falla.
• Muchos informes de “actualización encontrada pero no aplicada” son rechazos de política/configuración en lugar de retraso en la caché, especialmente cuando el mensaje de respuesta incluye un error code.
• Utiliza npx @capgo/cli@latest app debug mientras reproduce el problema para ver detalles de solicitud y respuesta.

Códigos de falla comunes

disable_auto_update_to_major

Causa

Su canal bloquea las actualizaciones principales (disable_auto_update = major) y la versión mayor del paquete objetivo supera la versión de base del dispositivo.

Síntoma típico

version: 1.0.8 con old: 0.0.0 significa que el dispositivo informa la versión de base 0.0.0, por lo que las actualizaciones principales son rechazadas.

Cómo interpretarlo

El backend compara versiones principales utilizando la base de dispositivo old y objetivo version.

• Si el objetivo es 1.0.1, la base de versión principal debe ser 1 (por ejemplo 1.0.0).
• Si el objetivo es 10.0.1, la base de versión principal debe ser 10 (por ejemplo 10.0.0).

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

Establecer plugins.CapacitorUpdater.version en capacitor.config.* para que sea MAJOR se ajusta a la versión 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. Reconstruya e instale la aplicación nativa.

Opción B de solución: relajación de la política de canal

Permitir actualizaciones automáticas entre versiones mayores en la configuración de canal (solo si esa estrategia de lanzamiento es intencional).

Documentación relacionada:

• Versiones objetivo: Deshabilitar actualizaciones automáticas entre versiones mayores
• Canales: Deshabilitar 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 (minor o patch) que la actualización que se ofrece.

Solución

• Subir un paquete compatible con la política actual, o
• cambiar la política del canal en dashboard/CLI.

Documentación relacionada:

• Canales: Estrategias de desactivación de actualizaciones automáticas

disable_auto_update_to_metadata

Causa

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

Reparar

• Ajustar la base del dispositivo (CapacitorUpdater.version) con la versión nativa instalada del aplicativo, o
• ajustar min_update_version la estrategia del canal.

Documentación relacionada:

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

disable_auto_update_under_native

Causa

El canal impide las descargas hacia abajo por debajo de la base nativa.

Reparar

• Subir una versión de paquete mayor o igual a la base nativa, o
• desactivar la protección de descenso “bajo nativo” para ese canal.

Documentación relacionada:

• Versiones objetivo: Prevención de descenso automático

cannot_update_via_private_channel

Causa

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

Reparar

• Usar un canal diferente con la asignación de dispositivo habilitada, o
• hacer el canal público / habilitar la asignación de dispositivo.

Documentación relacionada:

• Canales: Usando setChannel() desde tu App

unknown_version_build / semver_error

Causa

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

Solución

• Establecer plugins.CapacitorUpdater.version a una versión válida semver como 1.2.3.
• Sincronizar y reconstruir la aplicación nativa.

Documentación relacionada:

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

unsupported_plugin_version

Causa

La versión del plugin del actualizador es demasiado antigua para las requisitos actuales del servidor.

Solución

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

disabled_platform_ios / disabled_platform_android

Causa

El canal tiene actualizaciones deshabilitadas para esa plataforma.

Solución

• Habilitar la pestaña de plataforma en el canal.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

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

Solución

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

key_id_mismatch

Causa

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

Solución

• Utiliza 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

• Establecer un canal de nube por defecto, o
• establecer defaultChannel en compilaciones de prueba, o
• asignar una sobrescritura de canal para el dispositivo.

Documentación relacionada:

• Canales

on_premise_app

Causa

El servidor de respaldo devolvió HTTP 429 con on_premise_app. Esto ocurre en tres situaciones:

1. El ID de la aplicación no existe en Capgo — la app_id que se envía desde el dispositivo no está registrada, por lo que el backend no tiene registro de ella.
2. La aplicación está marcada como de uso propio — la aplicación existe pero está configurada para actualizaciones autoadministradas, por lo que el punto de conexión de la nube de 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 registrado en el panel de control de Capgo. El backend no puede distinguir entre “aplicación desconocida” y “aplicación de uso propio”, por lo que devuelve el mismo error code.

Reparar

• Verificar que coincide exactamente con lo que se muestra en la consola de __CAPGO_KEEP_0__ (sensible a mayúsculas y minúsculas). app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
• Si la aplicación está intencionalmente en la nube privada, establece npx @capgo/cli@latest app add.
• a su punto de actualización hospedado en lugar de la URL de la nube de __CAPGO_KEEP_0__. plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• Lista de verificación rápida de diagnóstico

Sección titulada “Lista de verificación rápida de diagnóstico”

1. Confirmar
2. coincide con la versión de la aplicación nativa instalada. CapacitorUpdater.version Reparar
3. Confirma 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 errores de backend code.

¿Necesita más ayuda?

• Solución de problemas
• Cómo obtener ayuda