Problemas de Actualización Comunes

Cuando una comprobación de actualización falla, Capgo suele devolver un error code y un message en la /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 fallo.
• 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

disable_auto_update_to_major

Causa

Su canal bloquea actualizaciones importantes (disable_auto_update = major) y la versión mayor del paquete objetivo está por encima de la versión base del dispositivo.

Síntoma típico

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

¿Cómo interpretarlo?

El backend compara las versiones principales utilizando la versión base del dispositivo old y objetivo version.

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

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

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. Reconstruir y reinstalar la aplicación nativa.

Opción B: relaja la política de canal

Permitir actualizaciones automáticas entre versiones principales en ajustes de canal (solo si esa estrategia de lanzamiento es intencional).

Documentos relacionados:

• Objetivo de versión: Deshabilitar actualizaciones automáticas entre versiones principales
• Canales: Deshabilitar estrategias de actualización

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 ofrecida.

• minor bloquea cuando el paquete objetivo tiene un número mayor o menor que la versión nativa del dispositivo (version_build). Ejemplo: 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 paquete compatible con la política actual, o
• modificar la política de canal en el panel de control/CLI.

Documentación relacionada:

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

disable_auto_update_to_metadata

Causa

El canal utiliza la configuración de targeting basada en metadatos (version_numbery el umbral del dispositivo está por debajo del requerido min_update_version.

Solucionar

• Alinear el umbral del dispositivo (CapacitorUpdater.version) con la versión de la aplicación nativa instalada, o
• ajustar min_update_version / estrategia de 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 del umbral nativo.

Solucionar

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

Documentos relacionados:

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

Solución

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

Documentos relacionados:

• Canales: Uso de setChannel() desde tu aplicación

unknown_version_build / semver_error

Causa

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

Solución

• Establecer plugins.CapacitorUpdater.version a una versión válida de semver como 1.2.3.
• Sincronice y reconstruye 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 de actualizador es demasiado antigua para las requisitos actuales del backend.

Solución

• Actualizar @capgo/capacitor-updater.
• Ejecutar npx cap sync.
• Reconstruir e instalar la aplicación nativa nuevamente.

disabled_platform_ios / disabled_platform_android

Causa

El canal tiene actualizaciones desactivadas para esa plataforma.

Reparar

• Habilitar la opción de plataforma en el canal.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

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

Reparar

• Alinear las opciones del canal (”,”) con tu objetivo de prueba.allow_prod, allow_dev, allow_device, allow_emulatorSección titulada “fallo_de_llave_principal”

key_id_mismatch

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

Reparar

Reparar

• Use the same encryption key/public key across app config and bundle encryption workflow.

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 backend devolvió HTTP 429 con on_premise_app. Esto ocurre en tres situaciones:

1. El ID de la aplicación no existe en Capgo — el app_id enviado por el dispositivo no está registrado, por lo que el backend no tiene registro de él.
2. La aplicación está marcada como de uso en local — 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 aplicación de la organizació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 backend no puede distinguir entre ‘aplicación desconocida’ y ‘aplicación en el lugar’, por lo que devuelve el mismo error code.

Solución

• Verificar el app_id coincide 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, ejecuta npx @capgo/cli@latest app add.
• Si la aplicación está configurada para estar en el lugar, establece plugins.CapacitorUpdater.updateUrl a su punto de actualización autogestionado en lugar de la URL de la nube de Capgo.
• Si el plan de la organización ha expirado, renueva o actualiza el plan.

Lista de verificación rápida

1. Confirmar 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 instalada del app.
3. Confirmar la política del canal (disable_auto_update) coincide con la implementación prevista.
4. Confirmar que los ajustes de plataforma/construcción permiten este dispositivo.
5. Ejecutar npx @capgo/cli@latest app debug y leer el error de backend code.

Necesita más ayuda?

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

Siga adelante desde Problemas de actualización comunes

Si estás utilizando Problemas de Actualizaciones Comunes para planificar el trabajo de plugins nativos, conecta con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Directorio de Plugins de Capgo para el flujo de trabajo del producto en Directorio de Plugins de Capgo, Plugins de Capacitor por Capgo para el detalle de implementación en Plugins de Capacitor 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.