Aller au contenu principal

Dépannage et codes d'erreur

Lorsqu'une commande tk-ota-push (alias tkushpatch) échoue, la CLI retourne un code de sortie standard POSIX (sysexits.h) et affiche un message d'erreur explicite sur la sortie d'erreur standard (stderr).

Ce guide référence l'ensemble des codes de sortie et fournit les solutions pas-à-pas pour résoudre les incidents de compilation, d'authentification et de publication.

1. Tableau des codes de sortie de la CLI​

Code de sortieConstante POSIXCause exacte dans runner.dartRésolution rapide
0EX_OKExécution terminée avec succèsAucune action requise.
1EX_SOFTWAREErreur d'exécution générale, échec de compilation Flutter, altération de code natif ou rejet API (HTTP 4xx/5xx)Consulter le message d'erreur et la trace affichée ci-dessous.
64EX_USAGESyntaxe de commande invalide, option inconnue ou valeur d'argument hors limites (ex: --rollout 150)Vérifier la syntaxe avec tk-ota-push <commande> --help.
66EX_NOINPUTLe répertoire ciblé ne contient aucun fichier pubspec.yaml valideVérifier que vous êtes à la racine d'un projet Flutter ou passer --project <chemin>.
69EX_UNAVAILABLELa toolchain Shorebird est introuvable (~/.shorebird/bin/cache/flutter)Installer ou initialiser Shorebird sur la machine.

2. Diagnostics détaillés et résolutions pas-à-pas​

Erreur 1 : Toolchain Shorebird introuvable (Code 69)​

Toolchain Shorebird introuvable (~/.shorebird/bin/cache/flutter).

Diagnostic​

La méthode Toolchain.locate() inspecte $HOME/.shorebird/bin/cache/flutter (ou %USERPROFILE%\.shorebird\bin\cache\flutter sous Windows). Si le répertoire n'existe pas ou ne contient aucun moteur Flutter patché, la CLI s'arrête immédiatement.

Résolution​

  1. Installez Shorebird si ce n'est pas déjà fait : 
    curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash
  2. Initialisez le cache Flutter patché en exécutant au moins une commande Shorebird : 
    shorebird doctor
  3. Vérifiez la présence du dossier cache : 
    ls -la ~/.shorebird/bin/cache/flutter

Erreur 2 : Aucun pubspec.yaml dans . (Code 66)​

Aucun pubspec.yaml dans /Users/dev/workspace.

Diagnostic​

La commande a été exécutée en dehors d'un projet Flutter valide, ou l'argument passé à --project pointe vers un dossier inexistant.

Résolution​

  • Déplacez-vous dans le répertoire de votre projet Flutter : 
    cd chemin/vers/mon_application
    tk-ota-push patch ...
  • Ou précisez le chemin explicite du projet : 
    tk-ota-push patch --project /chemin/vers/mon_application ...

Erreur 3 : HTTP 409 Conflict — Release déjà verrouillée (Code 1)​

❌ ERREUR HTTP 409 CONFLICT — PROTECTION CONTRE LE 'RELEASE OVERWRITE'
   La Release '1.0.0+1' (android / aarch64) est DÉJÀ verrouillée sur le serveur !
   Empreinte SHA-256 de référence : 4f8b2c...

Diagnostic​

TkushPatch garantit l'immuabilité absolue des Releases de référence. Une fois qu'une Release (ex: 1.0.0+1) est publiée, son binaire d'origine ne peut plus jamais être écrasé, car les téléphones des utilisateurs sur le terrain dépendent de ce binaire pour calculer le différentiel binaire (différentiel binaire).

Résolution​

  • Si vous souhaitez publier un correctif OTA sans republier sur les Stores : utilisez la sous-commande patch au lieu de release : 
    tk-ota-push patch 1.0.0+1 -p android -m "Description du patch"
  • Si vous préparez une nouvelle version Store : incrémentez le numéro de version dans pubspec.yaml (ex: 1.0.0+2 ou 1.0.1+1) avant d'exécuter release : 
    tk-ota-push release 1.0.0+2 -p android --artifact aab

Erreur 4 : Altération de code natif détectée (Code 1)​

❌ ERREUR CRITIQUE D'INTÉGRITÉ NATIVE :
   Des modifications de code natif ont été détectées entre la Release
   de référence et le patch que vous tentez de publier :
   - classes.dex : MODIFIÉ (Code Kotlin/Java altéré)

Diagnostic​

Le NativeIntegrityScanner a détecté une modification dans les fichiers de bytecode Android (classes*.dex), le manifeste (AndroidManifest.xml), des bibliothèques C++ ou des frameworks iOS. Un patch OTA Flutter ne peut mettre à jour que le code Dart AOT ; s'il était distribué, l'application crasherait au démarrage chez l'utilisateur.

Résolution​

  • Ce changement requiert une soumission Store complète. Incrémentez la version dans pubspec.yaml et publiez une nouvelle Release : 
    tk-ota-push release 1.0.1+2 -p android --artifact aab
  • Si vous êtes certain que le changement ne concerne que des dépendances Dart pures (et que seul pubspec.lock a varié), utilisez le flag --force : 
    tk-ota-push patch 1.0.0+1 -p android --force -m "Mise à jour intl purement Dart"

Erreur 5 : Délai dépassé lors du login PKCE (Code 1)​

Échec de la connexion : Délai dépassé (aucun retour de l'interface Web)

Diagnostic​

La commande tk-ota-push login a démarré un serveur HTTP local sur 127.0.0.1, mais aucune redirection n'a été reçue dans le délai imparti de 3 minutes (navigateur bloqué, firewall local bloquant la boucle locale ou portail Web non connecté).

Résolution​

  1. Vérifiez que la console Web est joignable à l'adresse indiquée (ou passez --web-url https://console-ota.entreprise.com).
  2. Cliquez manuellement sur le lien d'autorisation affiché dans le terminal si le navigateur ne s'est pas ouvert automatiquement.
  3. En environnement CI/CD ou sur un serveur distant sans interface graphique, n'utilisez pas login : définissez plutôt la variable d'environnement OTA_API_KEY.

Erreur 6 : --rollout doit être compris entre 0 et 100 (Code 64)​

Erreur : --rollout doit être un entier compris entre 0 et 100 (reçu: 150).

Diagnostic​

La valeur fournie à l'option --rollout de la commande patch n'est pas un entier valide dans l'intervalle [0, 100].

Résolution​

Spécifiez un pourcentage entre 0 et 100 :

tk-ota-push patch 1.0.0+1 -p android --rollout 25 -m "Canary 25%"

Erreur 7 : Erreur HTTP 403 Forbidden lors d'une promotion (Code 1)​

Erreur lors de la promotion (403) : {"error":"FORBIDDEN","message":"Patch must be in STAGED status and approved by a different user"}

Diagnostic​

La promotion d'un patch vers le canal stable applique la règle des 4 yeux. Le serveur refuse la promotion si :

  • L'utilisateur tentant de promouvoir le patch est le même développeur que celui qui l'a publié (author_id == approver_id).
  • Le patch n'a pas été publié avec l'option --staged ou n'a pas encore reçu l'approbation requise.

Résolution​

  1. Connectez-vous avec un compte distinct disposant du rôle validateur (ROLE_SECURITY_OFFICER ou ROLE_TENANT_ADMIN).
  2. Validez le patch depuis la Console Web (onglet Gouvernance) ou exécutez promote avec la clé API de l'approbateur.