Erreurs Expo courantes et correctifs avec exemples pratiques

Introduction

Expo accélère le développement React Native, mais sa couche d’abstraction peut transformer une petite erreur de configuration en une trace de pile déroutante. Ce guide aide les développeurs, les consultants DevOps et les équipes techniques de startups à passer d’un problème observé à un résultat vérifié. Vous apprendrez à identifier la version installée, à comprendre la topologie de déploiement, à vérifier les prérequis et à inspecter le composant exact qui cause le problème.

L’approche adoptée tout au long de ce guide est celle de la sécurité opérationnelle : observer avant de modifier, limiter le rayon d’impact, utiliser des valeurs fictives plutôt que des secrets, vérifier le résultat et documenter la procédure de récupération si l’état attendu n’est pas atteint. Chaque correctif inclut la commande ou le signal qui confirme le succès, afin que vous puissiez l’appliquer en toute confiance, que vous travailliez en local, en CI/CD ou sur une version de préproduction.

Inventaire des versions et de l’environnement

De nombreuses erreurs Expo disparaissent lorsque vous alignez les versions du SDK, de la CLI et de l’environnement d’exécution natif. Avant de toucher au code, établissez un inventaire clair de l’environnement.

Commencez par des observations en lecture seule. Ces commandes ne modifient rien et vous donnent l’état actuel :

# Vérifier la version de la CLI Expo
expo --version
# Exemple de sortie attendue : 6.3.10

# Vérifier le SDK Expo installé dans package.json
node -e "console.log(require('./package.json').dependencies.expo)"
# Exemple de sortie attendue : ~51.0.28

# Lister les paquets Expo installés globalement
npm ls -g --depth=0 | grep expo
# Exemple de sortie attendue : [email protected]

# Vérifier la version actuelle de Node.js
expo diagnostics
# La sortie attendue inclut : la version de Node.js, la version de npm, la version de la CLI Expo et la version du SDK du projet

Enregistrez la sortie et horodatez-la. Si vous travaillez en équipe, stockez ces détails dans un journal de dépannage partagé. L’objectif est de capturer l’état de référence avant tout changement.

Prérequis pour exécuter ces commandes :

Node.js 18 LTS ou plus récent pour Expo SDK 49 et supérieur
npm 9+ ou yarn 1.22+ installé
Le répertoire du projet accessible depuis le terminal
Pour le débogage de EAS Build, un compte Expo valide et eas-cli installé globalement (npm install -g eas-cli)

Une fois la référence établie, définissez le résultat attendu avant toute intervention. Par exemple, si l’objectif est de passer du SDK 48 au SDK 51, la sortie attendue après la mise à niveau est que expo --version affiche le nouveau SDK et que npx expo start se lance sans erreur de dépendance.

Le plus petit changement justifié peut être de mettre à jour uniquement le paquet expo, et non l’ensemble du monorepo. Exécutez toujours npx expo install --fix après avoir modifié la version du SDK. Cette commande aligne toutes les dépendances React Native et Expo sur des versions compatibles :

npx expo install --fix
# Sortie attendue : une liste de paquets mis à jour vers des versions compatibles, par exemple :
# « The following packages were updated:
#  [email protected]
#  [email protected] »

Si la mise à niveau échoue en cours de route, le chemin de récupération est :

git checkout package.json package-lock.json
# Restaure l’ensemble de dépendances précédent qui fonctionnait
npx expo start --clear
# Efface le cache du bundler Metro et redémarre

Ne collez jamais de véritables identifiants, jetons ou clés privées dans une commande. Utilisez des variables d’environnement ou des fichiers de valeurs fictives avec des noms clairs comme EXPO_TOKEN=<votre-jeton> dans les exemples.

Chemin de configuration sécurisé

La source la plus courante d’erreurs Expo est un fichier de configuration contenant une valeur non prise en charge par le SDK actuel. Cette section couvre app.json/app.config.js, eas.json et metro.config.js.

Tout d’abord, observez la configuration du projet sans rien changer :

npx expo config --type public
# Sortie attendue : la configuration publique résolue, y compris les plugins, les versions et l’ID de projet EAS

Si vous devez inspecter un champ spécifique, utilisez --json et redirigez vers jq :

npx expo config --type public --json | jq '.expo.version'
# Exemple de sortie attendue : "1.0.0"

Lorsque vous voyez une erreur comme Plugin "expo-splash-screen" is not compatible with SDK 51, le correctif est souvent une mise à jour de version dans les plugins de app.json, et non une modification du code. Voici une séquence sûre :

Vérifiez la version du plugin actuellement déclarée :

node -e "console.log(require('./app.json').expo.plugins)"
# Exemple de sortie attendue : [ "expo-splash-screen" ]

Vérifiez la version compatible à partir de la documentation Expo ou du paquet du plugin :

npm view expo-splash-screen@latest version
# Exemple de sortie attendue : 0.27.5

Mettez à jour uniquement ce plugin dans app.config.js avec une version explicite. Voici un exemple minimal utilisant une configuration JavaScript avec une valeur fictive :

// app.config.js
module.exports = {
  expo: {
    name: "MyApp",
    slug: "my-app",
    version: "1.0.0",
    plugins: [
      ["expo-splash-screen", { backgroundColor: "#ffffff" }]
    ],
  },
};

Si vous devez épingler la version du paquet du plugin, exécutez :

npx expo install [email protected]

Vérifiez que la configuration se résout sans erreur :

npx expo config --type public
# Sortie attendue : aucune erreur, la configuration inclut le plugin avec la bonne version

Récupération si la configuration devient invalide : réinitialisez uniquement le fichier modifié à partir du contrôle de version, ou si vous utilisez app.config.js, annulez la modification et exécutez npx expo start --clear.

Évitez de placer des secrets directement dans app.json. Utilisez plutôt des variables d’environnement dans app.config.js avec process.env.API_URL et ne codez jamais en dur des identifiants de production.

Vérification et diagnostics

Lorsqu’une application Expo ne démarre pas, plante à l’exécution ou affiche un écran rouge, vous avez besoin d’une approche de diagnostic systématique. Cette section couvre la capture des journaux, l’état du bundler Metro et les vérifications spécifiques aux appareils.

Commencez par les diagnostics intégrés de la CLI Expo :

npx expo-doctor
# Sortie attendue : un rapport des problèmes potentiels concernant la configuration du projet et les dépendances,
# par exemple : « Found 2 issues: package.json has invalid dependency range for expo-updates, app.json is missing ios.bundleIdentifier »

Si expo-doctor ne signale aucun problème mais que l’application échoue toujours, capturez les journaux du bundler Metro avec une sortie verbeuse :

npx expo start --verbose
# Sortie attendue : journaux de bundling détaillés, y compris les transformations de fichiers et les erreurs de résolution de modules

Pour les erreurs d’exécution sur un appareil ou un émulateur, utilisez l’application Expo Go ou une version de développement, puis ouvrez les journaux de l’appareil :

npx expo start
# Appuyez ensuite sur 'j' pour ouvrir le débogueur dans Chrome, ou sur 'm' pour basculer le menu développeur sur Android

Pour lire les journaux système d’un appareil Android :

adb logcat | grep ReactNativeJS
# Sortie attendue : journaux de console JavaScript et erreurs de l’application en cours d’exécution

Pour le simulateur iOS :

xcrun simctl spawn booted log stream --predicate 'processImagePath endswith "MyApp"'
# Sortie attendue : flux de journaux continu pour le processus de l’application

Un diagnostic courant consiste à vérifier que tous les modules natifs sont liés. Exécutez cette commande pour voir la liste des modules natifs installés :

npx expo-modules-autolinking verify
# Sortie attendue : un tableau des modules installés et leur statut d’autolinking

Si un module est manquant, l’erreur dit souvent Cannot find native module 'ExpoCamera'. Pour vérifier la configuration d’autolinking :

npx expo-modules-autolinking search expo-camera
# Sortie attendue : chemin vers le module et sa version, par exemple :
# « expo-camera trouvé dans node_modules/expo-camera (version 14.0.6) »

Pour les erreurs liées au réseau, testez la connectivité aux services Expo :

curl -I https://exp.host
# Sortie attendue : HTTP/2 200 ou 301, indiquant que le service est joignable

Enregistrez toutes les sorties de commande avec des horodatages. Si vous déboguez en équipe, collez les lignes pertinentes, pas le journal entier, pour garder le fil de discussion concentré.

Modes de défaillance et récupération

Différents modes de défaillance nécessitent différentes stratégies de récupération. Cette section couvre les échecs spécifiques à Expo les plus fréquents : erreurs de bundling, conflits de dépendances, échecs de EAS Build et problèmes de mise à jour OTA.

Erreurs de bundling apparaissent souvent comme Unable to resolve module ./src/screens/Home ou SyntaxError: Unexpected token. Pour récupérer, effacez d’abord le cache de Metro et redémarrez :

npx expo start --clear
# Sortie attendue : le bundler Metro redémarre avec un cache propre

Si l’erreur persiste, vérifiez que le chemin du fichier existe et correspond exactement à l’importation, y compris la sensibilité à la casse. Sur Linux et macOS, les chemins sont sensibles à la casse ; sur Windows, ils ne le sont pas, ce qui peut entraîner des incohérences en CI/CD.

Conflits de dépendances se manifestent par Invariant Violation: requireNativeComponent: "RNCSafeAreaProvider" was not found in the UIManager. Cela signifie généralement qu’un module natif n’est pas lié ou a une incompatibilité de version. Réinstallez les dépendances à partir de zéro :

rm -rf node_modules
npm install
npx expo install --fix
# Sortie attendue : installation propre avec des versions de dépendances corrigées

Pour les échecs de EAS Build, consultez d’abord les journaux de construction en ligne avec :

eas build:list
# Sortie attendue : un tableau des constructions récentes avec leur statut, par exemple : « errored », « finished », « in-progress »

Pour afficher les journaux d’une construction spécifique :

eas build:view --platform android --json | jq '.logs'
# Sortie attendue : sortie complète du journal de construction, consultable pour les lignes d’erreur

Les erreurs courantes de EAS Build incluent un google-services.json manquant pour les notifications push Android ou un bundleIdentifier invalide dans app.json. La récupération consiste à ajouter le fichier à la racine du projet ou à corriger l’identifiant, puis à exécuter :

eas build --platform android --profile preview --non-interactive
# Sortie attendue : une nouvelle construction démarre et renvoie finalement une URL de construction

Échecs de mise à jour OTA se produisent lorsque expo-updates est mal configuré. Vérifiez votre configuration de mise à jour dans eas.json :

eas update:list
# Sortie attendue : une liste des mises à jour publiées avec horodatages et versions d’exécution

Si une mise à jour ne s’applique pas, vérifiez que la version d’exécution dans app.json correspond à celle du binaire. Utilisez les diagnostics expo-updates :

npx expo-updates diagnostics
# Sortie attendue : informations sur la configuration des mises à jour et le résultat de la dernière vérification

La récupération peut nécessiter un retour à une mise à jour précédente :

eas update:rollback --channel production
# Sortie attendue : confirmation que le retour en arrière a été lancé

Définissez toujours une vérification de récupération avant d’en avoir besoin. Par exemple : « Après le retour en arrière, l’application devrait charger la version 1.0.1, confirmé en vérifiant l’écran de débogage expo-updates dans la version de développement. »

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour toute session de dépannage Expo. Chaque élément inclut un exemple concret pour le rendre actionnable.

[ ] Capturer la référence de l’environnement : exécutez npx expo diagnostics et enregistrez la sortie avec un horodatage, par exemple 2025-04-01_10-00_expo-diagnostics.txt.
[ ] Vérifier la santé des dépendances : exécutez npx expo-doctor. Sortie attendue : aucun problème ou une liste d’éléments actionnables.
[ ] Reproduire l’erreur avec des étapes minimales : documentez le chemin de navigation exact, par exemple « Ouvrir l’application > Connexion > Appuyer sur 'Soumettre' > Écran rouge avec 'Cannot read property map of undefined' ».
[ ] Isoler le changement : utilisez git diff avant et après. Si vous travaillez sur une nouvelle fonctionnalité, mettez de côté les modifications non liées avec git stash.
[ ] Appliquer le plus petit correctif : par exemple, si l’erreur est une icône manquante, exécutez npx expo install @expo/vector-icons et mettez à jour l’importation.
[ ] Vérifier avec une commande en lecture seule : après avoir ajouté une icône, exécutez npx expo export --platform web --output-dir dist et vérifiez le dossier dist pour l’actif de l’icône.
[ ] Tester le chemin de récupération : avant d’appliquer un changement risqué, essayez la commande de retour en arrière en simulation si disponible, par exemple git checkout -- package.json puis npm install et npx expo start.
[ ] Documenter le résultat : dans le manuel de procédures de votre équipe, notez l’erreur, le correctif, la commande de vérification et la procédure de retour en arrière.
[ ] Sécuriser les secrets : ne journalisez jamais process.env.EXPO_TOKEN. Utilisez expo login de manière interactive ou stockez le jeton dans un gestionnaire de secrets CI/CD.
[ ] Examiner les dépendances connexes : vérifiez React Native, Android et GitLab CI/CD uniquement s’ils font partie de la chaîne d’erreur. Par exemple, si une construction CI échoue sur Android, assurez-vous que l’image Docker possède la bonne version du SDK Android.

Un exemple de ligne complétée pour un conflit de dépendances :

Étape	Exemple
Référence	`npx expo diagnostics` montre SDK 50, Node 20
Erreur	`RNCSafeAreaProvider not found`
Correctif	`rm -rf node_modules && npm install && npx expo install --fix`
Vérification	`npx expo start --clear`, l’application se charge sans écran rouge
Récupération	`git checkout package-lock.json && npm install`

Conclusion

Les erreurs Expo courantes deviennent gérables lorsque vous les traitez comme des événements liés à une version, observables et réversibles. Copier une commande sans vérifier les prérequis et la sortie attendue n’est pas une procédure opérationnelle ; c’est une supposition. Choisissez plutôt une vérification à faible risque pour votre problème actuel, enregistrez l’état actuel, exécutez le contrôle documenté, comparez le résultat avec le signal attendu et ne passez en revue que les dépendances qui affectent cette erreur, telles que React Native, Android ou GitLab CI/CD.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de récupération avant qu’un incident ne force la décision. Avec les exemples concrets de ce guide, vous pouvez passer d’une trace de pile à une construction stable de manière prévisible et révisable.