Problèmes de mise à jour courants

Lorsqu'une vérification de mise à jour échoue, Capgo renvoie généralement une error code et une message dans la /updates réponse. Cette page explique les échecs les plus courants et les correctifs les plus rapides.

À lire en priorité

• no_new_version_available est un état normal, pas un échec.
• De nombreux signalements « mise à jour détectée mais non appliquée » correspondent à des refus de politique ou de configuration plutôt qu'à un retard de cache, surtout lorsque la réponse inclut un error code
• Utilisez npx @capgo/cli@latest app debug lors de la reproduction du problème pour voir les détails de la requête/réponse.

Codes d'erreur courants

provider_infrastructure_request_blocked

Cause

L'application a Bloquer les requêtes d'infrastructure du fournisseur activé et la requête provient d'une plage d'adresses IP connue de Google ou Apple. Capgo bloque ces requêtes sur /updates, /stats, et /channel_self pour éviter que le trafic provenant du fournisseur ne soit traité comme du trafic d'appareil.

Résoudre

• Reproduisez la mise à jour depuis un appareil physique sur le réseau d'un utilisateur standard.
• N'utilisez pas de sondes hébergées dans le cloud ou de runners de datacenters de fournisseurs pour les vérifications de l'updater, des stats ou des canaux lorsque cette protection est activée.
• Si ce trafic est intentionnel, ouvrez l'onglet Informations de votre application et désactivez Bloquer les requêtes vers l'infrastructure du fournisseur. Réactivez-l’une fois le test terminé.

Les nouvelles applications ont cette protection activée par défaut. Les applications créées avant l'introduction de ce paramètre la conservent désactivée jusqu'à ce que vous l'activiez.

Détails de la réponse

• /updates préserve le contrat de réponse de l'updater et renvoie HTTP 200. Son corps inclut error, message, kind: "blocked", et provider ("google" ou "apple").
• /stats et /channel_self retourne HTTP 429 avec la même erreur code. Considérez cela comme un blocage intentionnel par la politique, et non comme une erreur de tentative temporaire.

disable_auto_update_to_major

Cause

Votre canal bloque les mises à jour majeures (disable_auto_update = major) et la version majeure du bundle cible est supérieure à la version de base de l'appareil.

Symptôme typique

version: 1.0.8 avec old: 0.0.0 means the device reports baseline 0.0.0, donc les mises à jour majeures sont rejetées.

Comment l'interpréter

Le backend compare les versions majeures via la baseline de l'appareil old et la cible version.

• Si la cible est 1.0.1, la version de base majeure doit être 1 (par exemple 1.0.0).
• Si la cible est 10.0.1, la version de base majeure doit être 10 (par exemple 10.0.0).

Solution A (recommandée) : aligner la version majeure de la baseline de l'appareil

Définissez plugins.CapacitorUpdater.version dans capacitor.config.* donc c'est MAJEURE correspond à la version MAJEURE du bundle que vous souhaitez livrer (par exemple 1.0.0 dans les 1.0.1, 10.0.0 dans les 10.0.1).

Appliquez ensuite cette config à l'app installée une seule fois :

1. Exécutez npx cap sync.
2. Refaites un build et réinstallez l'app native.

Solution B : assouplir la politique du canal

Autorisez les auto-updates entre versions majeures dans les paramètres du canal (uniquement si cette stratégie de déploiement est intentionnelle).

Docs associées :

• Ciblage de version : désactiver l'auto-update entre les versions majeures
• Canaux : désactiver les stratégies d'auto-update

disable_auto_update_to_minor / disable_auto_update_to_patch

Cause

La politique du canal est plus stricte (minor ou patch) que la mise à jour proposée.

• minor bloque lorsque le bundle cible a une version majeure ou mineure différente de la base native de l'appareil (version_build). Exemple : 1.2.3 -> 1.3.0 est bloqué.
• patch bloque tout changement de numéro majeur, mineur ou patch par rapport à version_build. Only suffix changes are allowed while MAJOR.MINOR.PATCH reste identique, comme 1.0.0-beta.1 -> 1.0.0-beta.2 ou 1.0.0+build.1 -> 1.0.0+build.2.

Solution

• Envoyez un bundle compatible avec la politique actuelle, ou
• modifiez la politique du canal dans le dashboard/CLI.

Docs associées :

• Canaux : désactiver les stratégies d'Auto Update

disable_auto_update_to_metadata

Cause

Le canal utilise un ciblage basé sur les métadonnées (version_number) and the device baseline is below required min_update_version.

Solution

• Aligner la baseline de l'appareil (CapacitorUpdater.version) avec la version de l'app native installée, ou
• ajuster min_update_version la stratégie de / canal.

Docs associées :

• Canaux : désactiver les stratégies d'Auto Update

disable_auto_update_under_native

Cause

Le canal empêche le downgrade en dessous de la baseline native.

Solution

• Envoyer un bundle avec une version supérieure ou égale à la baseline native, ou
• désactiver la protection contre le downgrade « under native » pour ce canal.

Docs associées :

• Ciblage de version : prévention du downgrade automatique

cannot_update_via_private_channel

Cause

Le canal sélectionné ou par défaut n'autorise pas l'auto-assignation de l'appareil.

Solution

• Utilisez un autre canal avec l'auto-assignation activée, ou
• rendez le canal public / activez l'auto-assignation.

Docs associées :

• Canaux : utiliser setChannel() depuis votre application

unknown_version_build / semver_error

Cause

La version de base de l'appareil est manquante (unknown) ou non semver valide.

Corriger

• Définissez plugins.CapacitorUpdater.version vers un semver valide comme 1.2.3.
• Synchronisez et recompilez l'app native.

Docs associées :

• Canaux : Versioning des bundles et canaux
• Dépannage : Les mises à jour ne s'appliquent pas

unsupported_plugin_version

Cause

La version du plugin Updater est trop ancienne pour les exigences actuelles du backend.

Solution

• Mettre à jour @capgo/capacitor-updater.
• Exécutez npx cap sync.
• Recompiler et réinstaller l'application native.

disabled_platform_ios / disabled_platform_android

Cause

Les mises à jour sont désactivées pour cette plateforme sur ce canal.

Solution

• Activer l'interrupteur de la plateforme sur le canal.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Cause

Le canal n'autorise pas le type de build ou la cible d'exécution actuelle.

Solution

• Alignez les options du canal (allow_prod, allow_dev, allow_device, allow_emulator) avec votre cible de test.

key_id_mismatch

Cause

La clé de chiffrement du bundle et la clé de l'appareil diffèrent.

Solution

• Utilisez la même clé de chiffrement/clé publique dans la config de l'app et le workflow de chiffrement du bundle.

no_channel / null_channel_data

Cause

Aucun canal valide n'a été résolu pour l'appareil.

Solution

• Définissez un canal par défaut sur le cloud, ou
• définissez defaultChannel dans les builds de test, ou
• assignez un override de canal pour l'appareil.

Docs associées :

• Canaux

on_premise_app

Cause

Le backend a renvoyé une erreur HTTP 429 avec on_premise_app. Cela se produit dans trois situations :

1. L'App ID n'existe pas dans Capgo — l' app_id envoyée par l'appareil n'est pas enregistrée, le backend n'en a donc aucune trace.
2. L'application est marquée comme on-premise — l'application existe mais est configurée pour des mises à jour auto-hébergées, l'endpoint cloud Capgo refuse donc de la servir.
3. Le plan de l'organisation est annulé — l'organisation de l'application n'a plus d'abonnement actif.

Erreur courante

A typo in plugins.CapacitorUpdater.appId (dans capacitor.config.ts) ou une discordance avec l'App ID enregistré dans le dashboard Capgo. Le backend ne peut pas distinguer une « application inconnue » d'une « application on-premise », il renvoie donc la même erreur code.

Résoudre

• Vérifiez que l' app_id correspond exactement à ce qui est affiché dans le dashboard Capgo (la casse est respectée).
• Si l'application n'est pas encore enregistrée, lancez npx @capgo/cli@latest app add.
• If the app is intentionally on-premise, set plugins.CapacitorUpdater.updateUrl sur votre endpoint de mise à jour auto-hébergé au lieu de l'URL cloud Capgo.
• Si le plan de l'organisation a expiré, renouvelez ou changez de plan.

Checklist de diagnostic rapide

1. Confirmez que l'ID de l'app et le canal sont corrects pour le build.
2. Confirmez que CapacitorUpdater.version matches installed native app version.
3. Confirmez que la politique du canal (disable_auto_update) correspond au déploiement prévu.
4. Vérifiez que les sélecteurs de plateforme/build autorisent cet appareil.
5. Exécutez npx @capgo/cli@latest app debug et lisez l'erreur backend code.

Besoin d'aide supplémentaire ?

• Troubleshooting
• Comment obtenir du support

Continuer depuis « Problèmes de mise à jour courants »

Si vous utilisez Problèmes de mise à jour courants pour planifier le travail sur un plugin natif, connectez-l’à Utiliser @capgo/capacitor-updater pour la fonctionnalité native dans Utiliser @capgo/capacitor-updater, Répertoire des plugins Capgo pour le workflow produit dans le répertoire des plugins Capgo, Plugins Capacitor par Capgo pour les détails d'implémentation dans les plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans « Ajouter ou mettre à jour des plugins », et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise.