Problemas comunes de actualización

Cuando falla la comprobación de actualizaciones, Capgo suele devolver un error code y una message en la /updates respuesta. Esta página explica los fallos más comunes y sus soluciones más rápidas.

Lee esto primero

• no_new_version_available es un estado normal, no un error.
• Muchos reportes de “se encontró una actualización pero no se aplicó” son rechazos por política o configuración en lugar de retrasos de caché, especialmente cuando la respuesta incluye un error code.
• Usa npx @capgo/cli@latest app debug mientras reproduces el error para ver los detalles de la petición/respuesta.

Códigos de error comunes

provider_infrastructure_request_blocked

Causa

La app tiene Bloquear peticiones de infraestructura del proveedor activado y la petición proviene de un rango de IPs conocido de datacenters de Google o Apple. Capgo bloquea estas peticiones en /updates, /stats, y /channel_self para evitar que el tráfico originado por el proveedor se trate como tráfico del dispositivo.

Solución

• Reproduce la actualización desde un dispositivo físico en una red de usuario normal.
• No uses probes en la nube ni runners de datacenters de proveedores para comprobaciones de updater, stats o channel-self mientras esta protección esté activa.
• Si ese tráfico es intencionado, abre la Información pestaña y desactiva Bloqueo de peticiones a la infraestructura del proveedor. Vuelve a activarlo cuando termine la prueba.

Las apps nuevas tienen esta protección activada por defecto. Las apps creadas antes de este ajuste la mantienen desactivada hasta que la habilites.

Detalles de la respuesta

• /updates mantiene el contrato de respuesta del updater y devuelve HTTP 200. Su cuerpo incluye error, message, kind: "blocked", y provider ("google" o "apple").
• /stats y /channel_self devuelve HTTP 429 con el mismo error code. Trátalo como un bloqueo de política intencional, no como un error de reintento temporal.

disable_auto_update_to_major

Causa

Tu canal bloquea actualizaciones mayores (disable_auto_update = major) y la versión mayor del bundle de destino es superior a la versión base del dispositivo.

Síntoma típico

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

Cómo interpretarlo

El backend compara las versiones major usando el baseline del dispositivo old y el target version.

• Si el target es 1.0.1, el major del baseline debe ser 1 (por ejemplo 1.0.0).
• Si el target es 10.0.1, el major del baseline debe ser 10 (por ejemplo 10.0.0).

Solución A (recomendada): alinea el major del baseline del dispositivo

Configurar plugins.CapacitorUpdater.version en capacitor.config.* así que el MAJOR coincide con el MAJOR del bundle que quieres entregar (por ejemplo, 1.0.0 para 1.0.1, 10.0.0 para 10.0.1).

Luego, aplica esta configuración a la app instalada una vez:

1. Ejecuta npx cap sync.
2. Reconstruye y reinstala la app nativa.

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

Permite auto-updates entre diferentes versiones MAJOR en la configuración del canal (solo si esa estrategia de rollout es intencional).

Docs relacionadas:

• Version Targeting: Desactiva el Auto-Update entre versiones mayores
• Canales: desactiva estrategias de Auto Update

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 bundle de destino tiene una versión mayor o menor distinta a la base nativa del dispositivo (version_build). Ejemplo: 1.2.3 -> 1.3.0 está bloqueado.
• patch bloquea cualquier cambio en el número mayor, menor o patch desde version_build. Solo se permiten cambios en el 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.

Solución

• Sube un bundle compatible con la política actual, o
• cambia la política del canal en dashboard/CLI.

Docs relacionadas:

• Canales: desactiva estrategias de Auto Update

disable_auto_update_to_metadata

Causa

El canal usa segmentación basada en metadata (version_number) y el baseline del dispositivo es inferior al requerido min_update_version.

Solución

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

Docs relacionadas:

• Canales: desactiva estrategias de Auto Update

disable_auto_update_under_native

Causa

El canal evita downgrades por debajo de la base nativa.

Solución

• Sube una versión de bundle mayor o igual a la base nativa, o
• desactiva la protección contra downgrade “under native” para ese canal.

Docs relacionadas:

• Segmentación por versión: prevención de downgrade automático

cannot_update_via_private_channel

Causa

El canal seleccionado/predeterminado no permite la autoasignación del dispositivo.

Solución

• Usa otro canal con la autoasignación habilitada, o
• haz público el canal / habilita la autoasignación.

Docs relacionadas:

• Canales: uso de setChannel() desde tu app

unknown_version_build / semver_error

Causa

Falta la versión base del dispositivo (unknown) o no semver válido.

Solución

• Configurar plugins.CapacitorUpdater.version con una semver válido como 1.2.3.
• Sincroniza y reconstruye la app nativa.

Docs relacionadas:

• Channels: Bundle Versioning y Channels
• Troubleshooting: Updates not applying

unsupported_plugin_version

Causa

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

Solución

• Actualizar @capgo/capacitor-updater.
• Ejecuta npx cap sync.
• Reconstruye y reinstala la app nativa.

disabled_platform_ios / disabled_platform_android

Causa

Channel has updates disabled for that platform.

Solución

• Activa el toggle de plataforma en el channel.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

El canal no permite el tipo de build o el runtime target actual.

Solución

• Ajusta las opciones del channel (allow_prod, allow_dev, allow_device, allow_emulator) con tu target de prueba.

key_id_mismatch

Causa

Bundle encryption key and device key differ.

Solución

• Usa la misma clave de cifrado/clave pública en la config de la app y en el workflow de cifrado del bundle.

no_channel / null_channel_data

Causa

No se pudo resolver un canal válido para el dispositivo.

Solución

• Configura un canal por defecto en la nube, o
• configura defaultChannel en builds de prueba, o
• asigna un channel override al dispositivo.

Docs relacionadas:

• Canales

on_premise_app

Causa

El backend devolvió HTTP 429 con on_premise_app. Esto ocurre en tres situaciones:

1. El App ID 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 app está marcada como on-premise — la app existe pero está configurada para actualizaciones self-hosted, por lo que el endpoint de la nube de Capgo rechaza servirla.
3. El plan de la organización está cancelado — la organización de la app ya no tiene una suscripción activa.

Error común

A typo in plugins.CapacitorUpdater.appId (en capacitor.config.ts) o una falta de coincidencia con el app ID registrado en el dashboard de Capgo. El backend no distingue entre una “app desconocida” y una “app on-premise”, así que devuelve el mismo error code.

Solución

• Verifica el app_id coincide exactamente con lo que se muestra en el dashboard de Capgo (distingue mayúsculas de minúsculas).
• Si la app aún no está registrada, ejecuta npx @capgo/cli@latest app add.
• Si la app es intencionalmente on-premise, establece plugins.CapacitorUpdater.updateUrl a tu endpoint de actualización self-hosted en lugar de la URL de la nube de Capgo.
• Si el plan de la organización expiró, renueva o mejora el plan.

Checklist de diagnóstico rápido

1. Confirma que el app ID y el channel son correctos para el build.
2. Confirmar CapacitorUpdater.version coincide con la versión de la app nativa instalada.
3. Confirma que la política del canal (disable_auto_update) coincida con el despliegue previsto.
4. Confirma que los selectores de plataforma/build permitan este dispositivo.
5. Ejecuta npx @capgo/cli@latest app debug y lee el error del backend code.

¿Necesitas más ayuda?

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

Continuar desde Problemas comunes de actualización

Si estás usando Problemas comunes de actualización para planificar el trabajo con plugins nativos, conéctalo con Al usar @capgo/capacitor-updater para la funcionalidad nativa al usar @capgo/capacitor-updater, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.