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 de error code.
• Usar npx @capgo/cli@latest app debug mientras se reproduce el problema para ver detalles de solicitud/resposta.

Códigos de falla comunes

disable_auto_update_to_major

Causa

Su canal bloquea las actualizaciones importantes (disable_auto_update = majory el paquete objetivo tiene una versión mayor que la versión de referencia del dispositivo.

Síntoma típico

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

Cómo interpretarlo

El back-end compara las versiones principales utilizando la versión de referencia del dispositivo old y objetivo version.

• Si el objetivo es 1.0.1, la versión principal de la referencia del dispositivo 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).

Corrija opción A (recomendada): alinee la línea base principal del dispositivo

Establecer plugins.CapacitorUpdater.version en capacitor.config.* así que MAJOR coincida con el MAJOR del paquete que desea 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 de canal (solo si esa estrategia de lanzamiento es intencional).

Documentación relacionada:

• Versión de destino: 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 (minor o patch) que la actualización ofrecida.

Solución

• Subir un paquete 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

Causa

El canal utiliza la configuración de targeting basada en metadatos (version_number) y la versión del dispositivo está por debajo de la requerida min_update_version.

Solución

• Alinear la versión del dispositivo (CapacitorUpdater.version) con la versión nativa de la aplicación instalada, o
• ajustar min_update_version Estrategia de canal.

Documentos relacionados:

• 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 línea base nativa.

Solución

• Subir una versión de paquete mayor o igual a la línea base nativa, o
• deshabilitar la protección contra descargas hacia abajo 'bajo nativo' para ese canal.

Documentos relacionados:

• Versionamiento objetivo: Prevención de descargas hacia abajo automáticas

cannot_update_via_private_channel

La causa

El canal seleccionado/por defecto no permite la asignación automática del dispositivo.

Solución

• Utilice un canal diferente que permita la asignación automática, o
• haga que el canal sea público / habilite la asignación automática.

Documentación relacionada:

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

unknown_version_build / semver_error

La causa

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

Reparar

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

Documentación relacionada:

• Canales: Versión del 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.

Reparar

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

Reparar

• Habilitar el interruptor de plataforma en el canal.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

El canal prohíbe el tipo de compilación actual o el objetivo de tiempo de ejecución.

Reparar

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

Reparar

• Utiliza la misma clave de cifrado/clave pública en la configuración de la aplicación y en el flujo de trabajo de cifrado de paquetes.

no_channel / null_channel_data

Causa

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

Reparar

• Establecer un canal de nube por defecto, o
• establecer defaultChannel en compilaciones de prueba, o
• asignar un override 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 El dispositivo no ha registrado el dispositivo, por lo que el backend no tiene registro de él.
2. La aplicación está marcada como de uso 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 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 registrado en el panel de control Capgo. El backend no puede distinguir entre “aplicación desconocida” y “aplicación de uso en sitio”, por lo que devuelve el mismo error code.

Solución

• Verificar que app_id coincida exactamente con lo que se muestra en el panel de control Capgo (sensible a mayúsculas y minúsculas).
• If the app is not registered yet, run npx @capgo/cli@latest app add.
• If the app is intentionally on-premise, set plugins.CapacitorUpdater.updateUrl a su endpoint de actualización autoalojada en lugar de la URL de la nube Capgo.
• If the organization plan expired, renew or upgrade the plan.

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

1. Confirmar que el ID de la aplicación y el canal son correctos para la compilación.
2. Confirmar CapacitorUpdater.version coincide con la versión nativa de la aplicación instalada.
3. Confirmar que 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. Ejecuta y lee el error de backend __CAPGO_KEEP_0__. npx @capgo/cli@latest app debug and read backend error code.

Sección titulada “Necesitas más ayuda?”

• Cómo obtener ayuda
• Sigue adelante desde Problemas de actualización comunes

Sección titulada “Sigue adelante desde Problemas de actualización comunes”

Problemas de actualización comunes para planificar el trabajo de plugin nativo, conecta con Usando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-actualizador Using @capgo/capacitor-updater para la capacidad nativa en Usando @capgo/capacitor-actualizador, Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, 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.