Problemas de Actualización Comunes

Cuando un control de actualizaciones falla, Capgo suele devolver un error code y un message en el /updates 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 la respuesta incluye un ‘ error code.
• Usa 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 Block provider infrastructure requests protegido y el pedido provino de un rango de direcciones IP de un centro de datos conocido de Google o Apple. Capgo bloquea estos pedidos en /updates, /stats, and /channel_self evitar que el tráfico originado por el proveedor se trate como tráfico de dispositivo.

Fix

• Reproduce la actualización desde un dispositivo físico en una red de usuario normal.
• Do not use cloud-hosted probes or provider datacenter runners for updater, stats, or channel-self checks while this protection is enabled.
• Si ese tráfico es intencional, abre la aplicación de tu Information pulsa el botón de tab y desactive Block provider infrastructure requests. Re-enablelo cuando la prueba esté completa.

New apps have this protection enabled by default. Apps created before the setting was introduced keep it disabled until you enable it.

Detalles de respuesta

• /updates preserva el contrato de respuesta del actualizador y devuelve HTTP 200Su cuerpo incluye error, message, kind: "blocked", y provider ("google" o "apple").
• /stats y /channel_self devuelve HTTP 429 con el mismo error code. Considera esto como una política de bloqueo intencional, no como una condición de retry transitoria.

disable_auto_update_to_major

Causa

Su canal bloquea actualizaciones importantes (disable_auto_update = major) and the target bundle major is above the device baseline version.

Tipo de síntoma

version: 1.0.8 con old: 0.0.0 reporta el dispositivo el umbral 0.0.0, so major upgrades are rejected.

Cómo interpretarlo

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

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

Ajustar la base de dispositivo principal (recomendado)

Establecer plugins.CapacitorUpdater.version in capacitor.config.* in entonces su coincide con la versión MAJOR del paquete que deseas entregar (por ejemplo 1.0.0 for 1.0.1, 10.0.0 for 10.0.1).

Aplicar luego esta configuración a la aplicación instalada.

1. Ejecutar npx cap sync.
2. Reconstruya y reinstale la aplicación nativa.

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

Allow cross-major auto-updates in channel settings (only if that rollout strategy is intentional).

Documentación relacionada:

• Version Targeting: Disable Auto-Update Across Major Versions
• Channels: Disable Auto Update strategies

disable_auto_update_to_minor / disable_auto_update_to_patch

Causa

La política de canal es más estricta (minor o patchque la actualización que se ofrece.

• minor obstruye cuando el paquete objetivo tiene un número mayor o menor que el de la línea base nativa del dispositivo (version_buildEjemplo: 1.2.3 -> 1.3.0 está bloqueado.
• patch obstruye cualquier cambio de número mayor, menor o parche desde version_buildSolo se permiten cambios de sufijo mientras MAJOR.MINOR.PATCH se mantiene igual, como 1.0.0-beta.1 -> 1.0.0-beta.2 o 1.0.0+build.1 -> 1.0.0+build.2.

Fix

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

Documentos relacionados:

• Channels: Disable Auto Update strategies

disable_auto_update_to_metadata

Causa

Channel uses metadata-based targeting (version_number) and the device baseline is below required min_update_version.

Solución

• Alinea la versión base del dispositivo (CapacitorUpdater.version) with installed native app version, or
• ajusta min_update_version la estrategia del canal.

Documentación relacionada:

• Channels: Disable Auto Update strategies

disable_auto_update_under_native

Cause

El canal impide descargas hacia abajo por debajo del umbral nativo.

Solución

• Subir una versión de paquete mayor o igual a la base nativa, o
• desactivar la protección de downgrade nativa para ese canal.

Documentación relacionada:

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

cannot_update_via_private_channel

Cause

Selected/default channel does not allow device self-assignment.

Solución

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

Documentos relacionados:

• Canales: Usar setChannel() desde su aplicación

unknown_version_build / semver_error

Causa

Versión base del dispositivo en falta ("unknown) o no es válida semver.

Solución

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

Documentos relacionados:

• Canales: Versión de paquete y canales
• Troubleshooting: Updates not applying

unsupported_plugin_version

Causa

Updater plugin version is too old for current backend requirements.

Solución

• Actualiza @capgo/capacitor-updater.
• Ejecuta npx cap sync.
• Rebuild and reinstall native app.

disabled_platform_ios / disabled_platform_android

Causa

Channel has updates disabled for that platform.

Solución

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

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

Channel disallows current build type or runtime target.

Solución

• Alinea opciones de canal (allow_prod, allow_dev, allow_device, allow_emulatorSección titulada “key_id_mismatch”

key_id_mismatch

Causa

Bundle encryption key and device key differ.

Solución

• 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

• Establezca un canal por defecto en la nube, o
• establezca defaultChannel en compilaciones de prueba, o
• assign channel override for device.

Documentos relacionados:

• Canales

on_premise_app

Cause

El servidor de backend devolvió HTTP 429 con on_premise_appEl servidor de respaldo devolvió HTTP 429 con

1. La aplicación no existe en Capgo — the app_id sent by the device is not registered, so the backend has no record of it.
2. La aplicación está marcada como de uso privado. — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
3. El plan de organización ha sido cancelado --- la organización de la aplicación ya no tiene una suscripción activa.

Error común

A typo in plugins.CapacitorUpdater.appId (en capacitor.config.ts) o una incompatibilidad con el ID de la aplicación registrado en la consola de Capgo. El servidor no puede distinguir entre ‘aplicación desconocida’ y ‘aplicación en el sitio’, por lo que devuelve el mismo error code.

Solución

• Verifique que app_id coincide exactamente con lo que se muestra en la consola de Capgo.
• Si la aplicación no está registrada aún, ejecute npx @capgo/cli@latest app add.
• Si la aplicación está intencionalmente en el sitio. plugins.CapacitorUpdater.updateUrl a su punto de actualización autogestionado en lugar de la URL de nube de Capgo.
• Si el plan de la organización ha expirado, renueve o mejore el plan.

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

1. Confirm app ID and channel are correct for the build.
2. Confirmar CapacitorUpdater.version matches installed native app version.
3. Confirme que la política del canal (“disable_auto_update) coincide con la implementación prevista.
4. Confirm platform/build target toggles allow this device.
5. Ejecutar npx @capgo/cli@latest app debug y leer el error de backend code.

¿Necesita más ayuda?

• Troubleshooting
• Cómo obtener ayuda

Keep going from Common Update Problems

Si estás utilizando Problemas de Actualización Comunes to plan native plugin work, connect it with Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Directorio de Plugins de Capgo for the product workflow in Capgo Plugin Directory, Plugins de Capacitor por Capgo para los detalles de implementación en Capacitor Plugins por Capgo Agregar o Actualizar Plugins para los detalles de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives.