Depuración

Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.

Entender los logs en la nube

Si recibes un rechazo de la nube code y necesitas guías de solución más detalladas, consulta Problemas comunes de actualización.

Los logs de Capgo pueden incluir metadatos del evento. En el dashboard, filtra por la acción en snake_case code y haz clic en la celda de metadatos para copiar el payload JSON completo. Los metadatos son especialmente útiles en eventos de crash y WebView, ya que pueden incluir el mensaje de error, la URL de origen, la línea y la columna, el estado del proceso, la presión de memoria o el motivo específico de la plataforma. Los logs antiguos aún pueden mostrar los alias camelCase heredados que se indican entre paréntesis.

Cada título de sección coincide con la acción code que aparece en la tabla de logs de la consola, para que puedas ir directamente a ella.

Límites del plan y respuestas normales

Rechazos del backend relacionados con facturación, throttling o estados que no son errores.

`InvalidIp`

Qué significa

Capgo detectó tráfico que parece provenir de Google o de infraestructura cloud. Las actualizaciones con menos de cuatro horas de antigüedad se ignoran para que el tráfico de bots no se cuente como dispositivos facturables.

Qué hacer

Ignora esto en usuarios reales. Reintenta desde redes normales y dispositivos reales, o espera y vuelve a consultar más tarde.

`provider_infrastructure_request_blocked`

Qué significa

Tu app está configurada para bloquear peticiones desde rangos de IP conocidos de centros de datos de Google y Apple. La protección aplica a las comprobaciones de update, stats y peticiones de channel-self, por lo que los probes alojados en la nube y los runners del proveedor pueden recibir esta respuesta incluso si la configuración de la app es válida.

Qué hacer

Reintenta desde un dispositivo físico en una red de usuario normal. Si el tráfico del proveedor es intencional, desactívalo temporalmente Bloquear peticiones de infraestructura del proveedor en la app Información pestaña, y vuelve a activarlo tras la prueba. Las apps nuevas tienen esta opción activada por defecto; las existentes mantendrán su configuración anterior hasta que se cambie.

`needPlanUpgrade`

Qué significa

Tu organización alcanzó el límite de su plan o de dispositivos. El dispositivo no recibirá actualizaciones hasta que subas de plan o el próximo ciclo de facturación reinicie el uso.

Qué hacer

Mejora tu plan en el dashboard o espera al próximo ciclo de facturación.

`noNew`

Qué significa

El dispositivo ya tiene el último bundle disponible para su channel. Este es un estado normal, no un error.

`rateLimited`

Qué significa

El dispositivo envió demasiadas solicitudes de update o de channel en un periodo corto.

Qué hacer

Deja de llamar a las APIs de update dentro de render loops. Llámalas setChannel / getChannel solo desde acciones de usuario y configura defaultChannel en capacitor.config.

Formato de versión

Rechazos del backend causados por metadatos de versión nativa inválidos.

`semver_error`

Qué significa

Falta la versión de la app nativa en la configuración o no es un semver válido (x.y.z).

Qué hacer

Configurar plugins.CapacitorUpdater.version para un semver válido, verifícalo en el Probador de SemVer, luego reconstruye y reinstala la app nativa.

Plataforma y target de build

Rechazos del backend cuando la política del canal bloquea una plataforma, tipo de build o clase de dispositivo.

`disablePlatformIos`

Qué significa

El dispositivo ejecuta iOS, pero las actualizaciones de iOS están desactivadas para este canal.

Qué hacer

Activa iOS en el canal si fue un error, o redirige los builds de iOS a un canal dedicado si el bloqueo es intencional.

`disablePlatformAndroid`

Qué significa

El dispositivo ejecuta Android, pero las actualizaciones de Android están desactivadas para este canal.

Qué hacer

Habilita Android en el canal si fue un error, o redirige los builds de Android a un canal dedicado si el bloqueo es intencional.

`disablePlatformElectron`

Qué significa

El dispositivo ejecuta Electron, pero las actualizaciones de Electron están desactivadas para este canal.

Qué hacer

Habilita Electron en el canal si fue un error, o redirige los builds de Electron a un canal dedicado si el bloqueo es intencional.

`disableDevBuild`

Qué significa

El dispositivo es un dev build, pero los dev builds están bloqueados para este canal.

Qué hacer

Permite dev builds en un canal de test, o mantén este canal solo para release y mueve los dispositivos de desarrollo a otro canal.

`disableProdBuild`

Qué significa

Un build de producción llamado /updates, pero las actualizaciones de producción están bloqueadas para este canal.

Qué hacer

Permite actualizaciones de producción en el canal si fue un error, o redirige los builds de producción al canal correcto.

`disableDevice`

Qué significa

Se bloqueó un teléfono o tablet real porque este canal bloquea dispositivos reales.

Qué hacer

Habilita actualizaciones en dispositivos reales si fue un error, o mantén la restricción y redirige los dispositivos reales a otro canal.

`disableEmulator`

Qué significa

El dispositivo es un emulador, pero las actualizaciones de emuladores están desactivadas para este canal.

Qué hacer

Activa las actualizaciones en un canal de test, o mantén este canal bloqueado para emuladores y usa otro para validación.

Reglas de compatibilidad de auto-update

Rechazos del backend cuando las reglas de semver o metadatos bloquean el bundle de destino.

`disableAutoUpdate`

Qué significa

El auto-update está desactivado por la política de compatibilidad del canal. Los metadatos incluyen auto_update con una regla coincidente como major, minor, patch, metadata, o none.

Qué hacer

Cambia la política de auto-update del canal para permitir el rollout previsto.

`disableAutoUpdateUnderNative`

Qué significa

El canal tiene un bundle más antiguo que la versión base del dispositivo y bloquea el envío de actualizaciones para versiones nativas inferiores.

Qué hacer

Publica un bundle igual o superior al baseline nativo, o desactiva la protección under-native en el canal.

`disableAutoUpdateMetadata`

Qué significa

El canal requiere min_update_version, pero la versión nativa del dispositivo está por debajo de ese umbral.

Qué hacer

Configurar min_update_version en el bundle o release de una versión nativa más reciente.

`disableAutoUpdateToMajor`

Qué significa

El canal bloquea saltos de versión mayor, por ejemplo 1.x.x a 2.x.x.

Qué hacer

Alinea la estrategia de canales con tu plan de rollout mayor, o permite saltos mayores en este track. Ver Problemas comunes de actualización.

`disableAutoUpdateToMinor`

Qué significa

El canal bloquea saltos de versión minor respecto a la base nativa del dispositivo (version_build), por ejemplo 1.2.3 a 1.3.0.

Qué hacer

Alinea la estrategia de canales con tu plan de rollout, o permite saltos de versión minor en este track.

`disableAutoUpdateToPatch`

Qué significa

El canal bloquea cambios a nivel de patch manteniendo el mismo MAJOR.MINOR.PATCH prefijo; solo se permiten cambios en el sufijo.

Qué hacer

Alinea la cadencia de release con la política del canal, o permite saltos de patch en este track.

Configuración del canal

Rechazos del backend causados por una configuración de canal faltante o incompatible.

`cannotUpdateViaPrivateChannel`

Qué significa

El dispositivo intentó asociarse con un canal privado que no permite la autoasignación (allow_device_self_set es false) y el canal no es público.

Qué hacer

Activar allow_device_self_set en el canal o cambia el dispositivo a un canal público o permitido.

`channelMisconfigured`

Qué significa

El canal usa disable_auto_update: "version_number" pero el bundle min_update_version es null, por lo que Capgo no puede decidir qué dispositivos deben actualizarse.

Qué hacer

Completa la configuración de esa regla o cambia a un modo de auto-update más simple.

`NoChannelOrOverride`

Qué significa

No hay ningún canal predeterminado configurado y el dispositivo no tiene un canal de excepción.

Qué hacer

Configura un canal por defecto en el dashboard o en defaultChannel en el build.

Entrega y cifrado del bundle

Rechazos del backend cuando Capgo no puede servir o desencriptar el bundle.

`cannotGetBundle`

Qué significa

Capgo no pudo generar una URL de descarga firmada válida y no había un manifest de respaldo disponible.

Qué hacer

Vuelve a subir el bundle, regenera los manifests y verifica la configuración de R2 o del bundle público.

`missingBundle`

Qué significa

El bundle asignado al canal no tiene contenido descargable: no external_url, no r2_path, no es una versión integrada y no hay entradas en el manifest.

Qué hacer

Vuelve a generar y subir la versión, luego confirma que el bundle tenga contenido real.

`keyMismatch`

Qué significa

La clave pública de cifrado del dispositivo no coincide con la clave usada para cifrar el bundle. Los metadatos pueden incluir device_key_id, bundle_key_id, y version.

Qué hacer

Compara los IDs de la clave del dispositivo y del bundle en la consola. Publica con la misma clave y versiones de CLI/plugin coincidentes.

Configuración de la app y clientes legacy

Rechazos del backend causados por la configuración de la app o versiones de updater no compatibles.

`customIdBlocked`

Qué significa

La app envió un ID de dispositivo personalizado, pero esta app no acepta IDs personalizados, por lo que el ID se ignora.

Qué hacer

Deja de enviar IDs personalizados, o actívalos solo cuando tu flujo de trabajo lo requiera.

`blocked_by_server_url`

Qué significa

server.url está configurado en Capacitor, por lo que la WebView carga una URL remota en lugar de archivos locales del bundle. Los live updates de Capgo requieren archivos locales y server.url no se recomienda en producción.

Qué hacer

Elimina o limpia server.url en builds de producción y mantén los payloads de actualización locales. Este code puede aparecer como un rechazo del backend o como una estadística del dispositivo.

`backend_refusal`

Qué significa

El plugin updater es v4, versión que el backend ya no acepta.

Qué hacer

Actualiza el plugin y CLI a v5+ (preferible v8) con Capacitor v5+, reconstruye y vuelve a publicar el bundle metadata.

Ciclo de vida de la actualización

Eventos en el dispositivo para el flujo de actualización, activación y rollback.

`ping`

Qué significa

Acción de prueba interna para verificar el pipeline de estadísticas.

`get`

Qué significa

Capgo envió la información de descarga de una nueva versión al dispositivo.

`set`

Qué significa

Se activó un bundle en el dispositivo.

`set_fail`

Qué significa

No se pudo activar un bundle en el dispositivo.

Qué hacer

Revisa los logs nativos con npx @capgo/cli@latest app debug y verifica la integridad del bundle, las rutas y notifyAppReady flujo.

`reset`

Qué significa

El dispositivo volvió al bundle integrado.

`delete`

Qué significa

Se eliminó un bundle en el dispositivo.

Fallos de descarga e instalación

Eventos del dispositivo para progreso de descarga, validación de archivos y errores de instalación.

`download_0`

Qué significa

La secuencia de descarga comenzó al 0% de progreso.

`download_10`

Qué significa

Se ha descargado un nuevo bundle; progreso al 10%.

`download_20`

Qué significa

Se ha descargado un nuevo bundle — progreso indicado al 20%.

`download_30`

Qué significa

Se ha descargado un nuevo bundle — progreso indicado al 30%.

`download_40`

Qué significa

Se ha descargado un nuevo bundle — progreso indicado al 40%.

`download_50`

Qué significa

Se ha descargado un nuevo bundle — progreso indicado al 50%.

`download_60`

Qué significa

Se ha descargado un nuevo bundle; el progreso indica 60%.

`download_70`

Qué significa

Se ha descargado un nuevo bundle; el progreso indica 70%.

`download_80`

Qué significa

Se ha descargado un nuevo bundle; el progreso indica 80%.

`download_90`

Qué significa

Se ha descargado un nuevo bundle; el progreso indica 90%.

`download_complete`

Qué significa

La descarga del bundle finalizó con éxito.

`download_manifest_start`

Qué significa

El dispositivo comenzó a descargar el manifiesto de la actualización.

`download_manifest_complete`

Qué significa

El dispositivo terminó de descargar el manifiesto de la actualización.

`download_zip_start`

Qué significa

El dispositivo comenzó a descargar el archivo del bundle.

`download_zip_complete`

Qué significa

El dispositivo terminó de descargar el archivo del bundle.

`download_manifest_file_fail`

Qué significa

Falló la descarga de una entrada del manifest. version_name usa version:fileName para identificar el asset.

Qué hacer

Corrige el asset faltante o bloqueado, regenera el manifest y vuelve a subir el bundle.

`download_manifest_checksum_fail`

Qué significa

Un archivo manifest no superó la validación de checksum.

Qué hacer

Vuelve a subir el bundle con una versión actual de CLI y verifica los checksums del manifest.

`download_manifest_brotli_fail`

Qué significa

No se pudo descomprimir un archivo manifest con Brotli.

Qué hacer

Verifica la configuración de compresión y vuelve a subir los assets afectados.

`download_fail`

Qué significa

Error al descargar el bundle.

Qué hacer

Revisa la conexión de red, la expiración de la URL firmada, el acceso al CDN y el almacenamiento del dispositivo.

`update_fail`

Qué significa

El bundle se instaló pero la app nunca llamó notifyAppReady, así que Capgo hizo un rollback.

Qué hacer

Llama a notifyAppReady() después de que tu app termine el bootstrapping. Texto del log nativo notifyAppReady was not called, roll back current bundle corresponde a este code.

`checksum_fail`

Qué significa

El bundle descargado no superó la validación del checksum. Causas habituales: un desajuste de CRC32 vs SHA256 por un upload antiguo con CLI, o un desajuste de la clave de cifrado en plugins antiguos que muestran el fallo de descifrado como un fallo de checksum.

Qué hacer

Vuelve a subir con un CLI/plugin actual (SHA256). Si usas cifrado, verifica que la clave pública de la app coincida con la clave de subida, o actualiza al plugin 8.3.0+ para obtener errores keyMismatch explícitos.

`decrypt_fail`

Qué significa

El bundle descargado no pudo descifrarse.

Qué hacer

Verifica las claves de cifrado y vuelve a subir el bundle con el par de claves correspondiente.

`windows_path_fail`

Qué significa

El zip contiene rutas no válidas de estilo Windows.

Qué hacer

Reconstruye el bundle en rutas Unix o sanitiza las rutas del archivo antes de subirlo.

`canonical_path_fail`

Qué significa

Las rutas de archivos dentro del zip no son canónicas.

Qué hacer

Corrige la generación de rutas del archivo antes del upload.

`directory_path_fail`

Qué significa

El zip contiene rutas de directorio no válidas.

Qué hacer

Corrige la estructura del archivo antes del upload.

`unzip_fail`

Qué significa

El dispositivo no pudo descomprimir el bundle descargado.

Qué hacer

Verifica la integridad del archivo y la compresión compatible.

`low_mem_fail`

Qué significa

La descarga falló por falta de memoria en el dispositivo.

Qué hacer

Reduce el tamaño del bundle o reintenta en un dispositivo con más memoria libre.

Salud de la app y eventos de WebView

Diagnósticos de crashes, memoria y WebView en el dispositivo. Revisa siempre el JSON de metadata en el dashboard.

`app_moved_to_background`

Qué significa

La app pasó a segundo plano.

`app_moved_to_foreground`

Qué significa

La app pasó a primer plano.

`app_crash`

Qué significa

Error en la capa de JavaScript o Capacitor. Los metadatos pueden incluir mensaje, stack, fuente y el contexto del bundle activo.

Qué hacer

Inspecciona metadatos y logs nativos. Combina el reporte de errores de JS y nativo (por ejemplo, Sentry) para localizar la ruta de code que falla.

`app_crash_native`

Qué significa

Crash en la plataforma nativa. Los metadatos incluyen plataforma, motivo, stack y detalles del proceso.

Qué hacer

Usa los logs de crash de Xcode o Logcat y correlaciónalos con el bundle activo de los metadatos.

`app_anr`

Qué significa

Evento de Android Application Not Responding.

Qué hacer

Inspecciona trazas de ANR en Logcat y reduce el bloqueo del hilo principal tras las actualizaciones.

`app_killed_low_memory`

Qué significa

El SO cerró la app debido a la presión de memoria.

Qué hacer

Reduce el uso de memoria tras activar la actualización e inspecciona los metadatos para ver indicadores de memoria disponible.

`app_killed_excessive_resource_usage`

Qué significa

El SO cerró la app por uso excesivo de recursos.

Qué hacer

Inspecciona los metadatos para ver el tipo de recurso o el motivo de la plataforma.

`app_initialization_failure`

Qué significa

El Updater o el inicio fallaron antes de que el runtime estuviera listo.

Qué hacer

Inspecciona los metadatos del paso fallido y el mensaje de error.

`app_memory_warning`

Qué significa

Advertencia de memoria en iOS.

Qué hacer

Inspecciona el contexto de memoria en los metadatos y reduce el uso pico tras las actualizaciones.

`webview_javascript_error`

Qué significa

Error de JavaScript no capturado en la WebView. Los metadatos pueden incluir el mensaje, la URL de origen, la línea, la columna y el stack.

Qué hacer

Instala el reporte de errores en las capas JS y nativa para capturar la línea exacta que falla en producción.

`webview_unhandled_rejection`

Qué significa

Rechazo de promesa no manejado en la WebView.

Qué hacer

Captura fallos asíncronos con reportes de errores de JS y nativos.

`webview_resource_error`

Qué significa

Un recurso de la WebView no pudo cargarse.

Qué hacer

Usa la URL de metadatos y el estado para arreglar assets o reglas de red.

`webview_security_policy_violation`

Qué significa

La política de seguridad de contenido bloqueó un recurso.

Qué hacer

Ajusta el CSP usando la directiva metadata y los detalles de la URI bloqueada.

`webview_unclean_restart`

Qué significa

La sesión anterior de WebView no se cerró correctamente, lo que puede indicar bucles de crash tras una actualización.

Qué hacer

Correlaciona con eventos de crash y errores de WebView antes y después del reinicio.

`webview_render_process_gone`

Qué significa

El proceso de renderizado de Android WebView ha finalizado.

Qué hacer

Inspecciona las señales de crash del renderer en los metadatos y logs nativos.

`webview_content_process_terminated`

Qué significa

El proceso de contenido de la WebView de iOS terminó.

Qué hacer

Inspecciona el bundle activo y la URL de la página desde los metadatos.

Contexto de entorno y canal

Eventos de contexto del dispositivo que ayudan a correlacionar el comportamiento de las actualizaciones con cambios en el OS, la versión nativa o el canal.

`os_version_changed`

Qué significa

Device OS version changed between checks.

`native_app_version_changed`

Qué significa

La versión nativa de la app store cambió, lo que ayuda a separar los cambios nativos de los del bundle web.

`getChannel`

Qué significa

El dispositivo consultó su canal actual.

`setChannel`

Qué significa

Se estableció el canal correctamente para el dispositivo.

`uninstall`

Qué significa

La app fue desinstalada o se borraron los datos de Capgo.

Estado del bundle

SUCCESS: instalación del bundle completada
ERROR: error al instalar o descargar
PENDING: descarga completada, pendiente de release
DELETED: bundle eliminado, aún aparece en stats
DOWNLOADING: descargando un bundle actualmente

Entender los logs del dispositivo

Comando de debug

Existe un comando de debug para usuarios de la nube de Capgo.

npx @capgo/cli@latest app debug

Esto te permitirá revisar todos los eventos de la app y encontrar una solución si las actualizaciones no se ejecutan.

Logs nativos de iOS

para encontrar tus logs en Xcode

Obtener el log del dispositivo en Xcode

Logs nativos de Android

para encontrar tus logs en Android Studio

Ver logs con Logcat

Mapeo de frases de logs nativos

Failed to download from se mapea a download_fail
notifyAppReady was not called, roll back current bundle se mapea a update_fail

Cómo encontrar el bundle descargado en un dispositivo

iOS

Para depurar en iOS, necesitas hacer un dump de la app en tu ordenador; puedes hacerlo así:

Xcode tiene una función integrada para inspeccionar el sistema de archivos de las apps instaladas por desarrolladores en un dispositivo iOS. Menú Window de Xcode mostrando la opción Devices and Simulators

Para lograrlo:

Conecta tu dispositivo al Mac y selecciona Window > Devices en la barra de menús de Xcode.
Selecciona tu dispositivo en el panel izquierdo, en la sección Devices.
Esto mostrará una lista de las apps instaladas por desarrolladores en ese dispositivo.
Selecciona la app que quieras inspeccionar y luego pulsa el icono de los 3 puntos cerca de la parte inferior de la pantalla.
Aquí puedes ver el sistema de archivos actual descargando un snapshot del mismo.

Panel de Xcode Devices con la opción de descargar el app container

Al seleccionar Download Container… se descargará y exportará un snapshot del sistema de archivos como un archivo .xcappdata que podrás explorar.

Archivo xcappdata descargado con el menú contextual Show Package Contents

Haz clic derecho en este archivo y selecciona Show Package Contents para abrir la carpeta.

Abre la carpeta de datos de la app y deberías ver varias carpetas como Documents, Library, tmp, etc.

Estructura de carpetas del app container de iOS mostrando Documents y Library

Luego encontrarás una versión en 2 carpetas:

library/NoCloud/ionic_built_snapshots es necesario tras reiniciar la app

y documents/versions para hot reload

Android

Para depurar en Android, debes acceder al dispositivo desde Android Studio:

Haz clic en View > Tool Windows > Device File Explorer o pulsa el botón Device File Explorer en la barra de la ventana de herramientas.
Selecciona un dispositivo de la lista desplegable.
Abre la ruta data/data/APP_NAME/ dónde APP_NAME es el ID de tu app.

Android Studio Device File Explorer muestra el directorio de datos de la app

Luego busca la versions carpeta para ver todas las versiones

Cómo entender los crash logs de producción en iOS

Cómo revisar los crash logs de tu app

Continúa desde Depuración

Si estás usando Depuració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.