Problèmes courants de mise à jour

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

À lire en priorité

• no_new_version_available est un état normal, pas un échec.
• De nombreux rapports « update found but not applied » correspondent à des refus de politique ou de configuration plutôt qu’à un retard de cache, surtout lorsque la réponse inclut un error code.
• Utiliser npx @capgo/cli@latest app debug pendant 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'IP de datacenter Google ou Apple connue. Capgo bloque ces requêtes sur /updates, /stats, et /channel_self afin d’empêcher le trafic émanant du fournisseur d’être traité comme du trafic d’appareil.

Corriger

• Reproduire la mise à jour depuis un appareil physique sur un réseau utilisateur standard.
• Ne pas utiliser de sondes hébergées dans le cloud ni de runners de datacenter fournisseur pour les vérifications updater, stats ou channel-self tant que cette protection est activée.
• Si ce trafic est intentionnel, ouvrez l’onglet Informations de votre application et désactivez Bloquer les requêtes d'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 gardent 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 contient 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 de politique intentionnel, et non comme une condition de retry 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 par old: 0.0.0 signifie que l’appareil signale la baseline 0.0.0, les mises à niveau majeures sont donc rejetées.

Comment l’interpréter

Le backend compare les versions majeures à l’aide de la baseline de l’appareil old et cible version.

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

Option A (recommandée) : aligner la version majeure de référence de l’appareil

Définissez plugins.CapacitorUpdater.version dans capacitor.config.* donc son MAJEUR correspond au MAJOR du bundle que vous souhaitez livrer (par exemple 1.0.0 pour 1.0.1, 10.0.0 pour 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

Autoriser les auto-updates cross-major 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 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 un numéro majeur ou mineur différent de la référence 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. Seuls les changements de suffixe sont autorisés tant que MAJOR.MINOR.PATCH reste identique, par exemple 1.0.0-beta.1 -> 1.0.0-beta.2 ou 1.0.0+build.1 -> 1.0.0+build.2.

Corriger

• 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 Auto Update

disable_auto_update_to_metadata

Cause

Le canal utilise un ciblage basé sur les métadonnées (version_number) et l'appareil est sous la version minimale requise min_update_version.

Corriger

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

Docs associées :

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

disable_auto_update_under_native

Cause

Le canal empêche les downgrades en dessous de la baseline native.

Corriger

• Envoyez une version de bundle supérieure ou égale à la baseline native, ou
• désactivez la protection contre les downgrades « 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-attribution des appareils.

Corriger

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

Docs associées :

• Canaux : utilisation de setChannel() depuis votre application

unknown_version_build / semver_error

Cause

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

Corriger

• Définissez plugins.CapacitorUpdater.version à un semver valide tels que 1.2.3.
• Synchronisez et recompilez l'app native.

Docs associées :

• Canaux : versionnage 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.

Corriger

• Mise à niveau @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 le canal.

Corriger

• Activez le toggle de 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.

Corriger

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

key_id_mismatch

Cause

Les clés de chiffrement du bundle et de l’appareil diffèrent.

Corriger

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

Corriger

• Définissez un canal par défaut cloud, ou
• configurer defaultChannel dans les builds de test, ou
• assignez un override de canal à l’appareil.

Docs associées :

• Canaux

on_premise_app

Cause

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

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

Erreur courante

A typo in plugins.CapacitorUpdater.appId (dans capacitor.config.ts) ou une discordance avec l'ID d'application 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.

Corriger

• Vérifier l' app_id correspond exactement à ce qui est affiché dans le dashboard Capgo (sensible à la casse).
• Si l'application n'est pas encore enregistrée, lancez npx @capgo/cli@latest app add.
• Si l'application est volontairement on-premise, configurez 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-l’ou passez à un plan supérieur.

Checklist de diagnostic rapide

1. Confirmez que l'ID de l'application et le canal sont corrects pour le build.
2. Confirmer CapacitorUpdater.version correspond à la version de l’app native installée.
3. Confirmez que la politique du canal (disable_auto_update) correspond au déploiement prévu.
4. Vérifiez que les commutateurs 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 courants de mise à jour pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-updater pour la capacité native dans « Utiliser @capgo/capacitor-updater », Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.