Les erreurs Flutter qui m'ont coûté des heures (et comment les régler en minutes)

Le charabia a toujours une cause

Quand tu construis avec Claude Code et que tu ne connais pas Flutter, les messages d'erreur font peur. Bonne nouvelle : chaque erreur a une cause précise, et la solution prend souvent deux minutes. Le vrai problème, c'est de savoir laquelle.

Voici celles que j'ai rencontrées le plus souvent.

Installation et environnement

• « Android license status unknown » : Android Studio est installé mais ses licences n'ont jamais été acceptées. Lance flutter doctor --android-licenses et réponds « y » partout.
• « flutter: command not found » : Flutter n'est pas dans le PATH. Ajoute le dossier flutter/bin à ton fichier .zshrc, puis recharge le terminal.
• « CocoaPods not installed » : Flutter a besoin de CocoaPods pour iOS. Installe-le avec Homebrew, puis lance pod install dans le dossier ios.

Flutter et Dart

• « RenderFlex overflowed by X pixels » : le contenu dépasse l'espace disponible, souvent une Column dans un parent qui ne défile pas. Enveloppe-la dans un SingleChildScrollView. Ma règle : au-delà de 3 ou 4 éléments, je l'anticipe.
• « setState() called after dispose() » : une opération asynchrone a fini après la fermeture de l'écran. Vérifie que le widget est encore monté avant de mettre à jour. À long terme, un gestionnaire d'état comme Riverpod évite le problème.
• « Null check operator used on a null value » : un point d'exclamation a été utilisé sur une valeur vide. Ma règle : ne jamais utiliser le point d'exclamation, toujours prévoir une valeur par défaut.
• « MissingPluginException » : un plugin natif n'est pas lié. La solution universelle : flutter clean, flutter pub get, pod install, puis relancer.

iOS et Xcode

• « Signing requires a development team » : ouvre le fichier .xcworkspace (pas le .xcodeproj), choisis ton équipe dans Signing & Capabilities et coche la signature automatique.
• « Archive failed » : fais un Clean Build Folder. Si ça échoue encore, supprime les Pods et le Podfile.lock, relance pod install, puis reconstruis.
• Rejet Apple pour description manquante : si l'app utilise la caméra, les photos ou la position, Info.plist doit expliquer pourquoi. Les phrases génériques sont refusées : Apple veut savoir pourquoi ton app en a besoin.

Android et Gradle

• « minSdkVersion 16 cannot be smaller than 21 » : monte la version minimale à 21 dans le fichier build.gradle de l'app.
• « Unsupported class file major version » : la version de Java ne correspond pas à celle de Gradle. Mets une version récente de Gradle dans le fichier gradle-wrapper.properties.

Publication sur l'App Store

• « Missing Export Compliance » : Apple demande si l'app utilise du chiffrement. Si tu n'utilises que HTTPS, déclare-le dans Info.plist avec la clé ITSAppUsesNonExemptEncryption à false.
• Un build qui plante à l'archive : dans 80 % des cas, flutter clean puis pod install règle le problème.

La règle qui vaut pour toutes les erreurs

Avant de chercher pendant deux heures, colle le message d'erreur complet dans Claude Code, pas seulement la dernière ligne, et demande la cause avant la correction. S'il ne trouve pas, donne-lui le contexte : la commande lancée, ce que tu venais de modifier.

Toutes ces erreurs, et beaucoup d'autres, sont rangées dans la « bible des erreurs » du [ByNeel Starter Kit](/kit).