Annexe B — Les 20 erreurs classiques (et leurs remèdes)

Le message exact (ou le symptôme) → la cause → le remède. Dans l’ordre approximatif de probabilité de rencontre.

Au développement

1. « Text strings must be rendered within a <Text> component » Texte nu dans une View — souvent le {count && …} avec count = 0. → Envelopper dans Text ; booléen à gauche des && (count > 0 &&). [3.1]

2. « Unable to resolve module X » Module pas installé, cache Metro périmé, ou faute de frappe d’import. → npx expo install X (pas pnpm add si natif) puis npx expo start -c. [2.1, 1.4]

3. Écran blanc / liste invisible, aucune erreur flex: 1 manquant dans la chaîne des parents — le composant mesure 0. → Element inspector, vérifier chaque maillon depuis la racine. [4.2]

4. « Cannot find native module ‘X’ » Le JS référence un module natif absent du conteneur : Expo Go ne l’a pas, ou dev build périmé. → Rebuild du dev build (le réflexe post-expo install d’un module natif). [11.1]

5. Le changement de config (app.json, plugin, tailwind) « ne fait rien » La config est lue au build/démarrage, pas à chaud. → expo start -c pour Metro/NativeWind ; rebuild pour le natif. [4.4, 11.3]

6. Ma classe NativeWind ne s’applique pas Fichier hors du glob content, cache, ou classe construite dynamiquement. → Vérifier tailwind.config.js content, -c, classes littérales en mapping. [4.4]

7. Image distante invisible Pas de dimensions — une URI n’a pas de taille intrinsèque connue. → width/height explicites (ou parent dimensionné + flex). [3.2]

8. Le tap sur un item de liste ne marche qu’au 2e coup (clavier ouvert) Le premier tap ferme le clavier. → keyboardShouldPersistTaps="handled" sur la FlatList. [3.5]

9. « VirtualizedLists should never be nested » FlatList dans une ScrollView de même axe. → ListHeaderComponent pour le contenu au-dessus de la liste. [3.6]

10. Texte de TextInput invisible en thème sombre Pas de color dans le style — noir sur noir. → Styler color ET placeholderTextColor explicitement. [3.5]

Timers, état, animations

11. Le timer « offre » du temps après un passage en arrière-plan Compteur décrémenté par ticks (gelés en background). → Stocker endsAt, comparer à Date.now() (l’horloge fait foi). [6.3]

12. « Tried to synchronously call a non-worklet function on the UI thread » Appel de code React (setState, router) depuis un worklet/callback Reanimated. → runOnJS(fn)(args). [10.2]

13. Affichage figé d’une shared value dans un Text {sv.value} au render : React n’est pas notifié. → useAnimatedStyle/Props, ou dériver un état React. [10.2]

14. Tous les items de la liste re-rendent à chaque frappe Props instables (fonctions inline, objets) sur des items mémoïsés. → React.memo + useCallback au parent + styles statiques. [3.4, 6.1]

Builds & distribution

15. « SDK location not found » (gradle) ANDROID_HOME absent ou terminal pas relancé. → Variables d’env du ch. 2.3, rouvrir le terminal. [2.3]

16. « INSTALL_FAILED_UPDATE_INCOMPATIBLE » Signatures différentes (debug vs release, perso vs Store). → Keystore unique pour local/cloud ; jamais de mise à jour croisée perso↔Store. [12.3, 13.2]

17. « INSTALL_FAILED_VERSION_DOWNGRADE » versionCode inférieur à l’installé. → autoIncrement EAS ; adb install -d en dev uniquement. [12.4]

18. L’OTA publiée n’arrive jamais Mauvais channel, runtimeVersion différente, ou test sur Metro (updates inactives en dev). → Vérifier channel du binaire, runtime des deux côtés, tester sur build release, ouvrir l’app DEUX fois. [12.5]

19. Ma modif du dossier android/ a disparu prebuild --clean a régénéré — le contrat CNG. → La vérité vit dans app.config.ts/config plugins, jamais dans le généré. [11.4]

20. Crash en release, invisible en dev (« ça marchait ! ») Plus de RedBox en release ; souvent : erreur réseau non gérée, code strippé, timing d’hydratation. → Sentry pour voir ; tester systématiquement un build release avant diffusion (matrice offline comprise). [12.2, 14.5]

La méthode générale de diagnostic

1. Lire le message en entier (la première ligne + le premier « Caused by »).
2. npx expo start -c (le cache Metro, coupable n°1).
3. npx expo-doctor (versions, config).
4. « Mon conteneur est-il à jour ? » (dev build après tout changement natif).
5. Reproduire sur un état propre : adb shell pm clear, voire prebuild --clean.
6. Chercher le message EXACT (guillemets) — GitHub issues d’Expo/RN avant Stack Overflow.