DEV Community

Cover image for How to Fix Expo Doctor Errors in Expo
Asta Silva
Asta Silva

Posted on

How to Fix Expo Doctor Errors in Expo

#reactnative #javascript #android #webdev

If you work with Expo long enough, you will probably run into expo-doctor.

You run:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

and instead of everything being green, you get something like:

✖ Check Expo config
✖ Check dependencies
✖ Check package versions
Enter fullscreen mode Exit fullscreen mode

Sometimes there is one problem.

Sometimes there are several.

And sometimes the output looks much worse than the actual problem.

The good thing is that expo-doctor is usually pretty clear about what it does not like. The tricky part is knowing what the warnings actually mean and which ones you need to fix.

Here is how I usually work through Expo Doctor errors without immediately changing half of the project.

First, run Expo Doctor by itself

Start with:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

Let it finish and read the full output.

Do not immediately start changing dependencies just because you see a red ✖.

Expo Doctor runs several checks, and a failure in one check does not necessarily mean your entire project is broken.

For example, you might see:

✖ Check that packages match versions required by installed Expo SDK
Enter fullscreen mode Exit fullscreen mode

That is very different from:

✖ Check for common project configuration problems
Enter fullscreen mode Exit fullscreen mode

The first one points toward dependency versions.

The second could require looking at your Expo configuration.

So the first step is simply figuring out which check actually failed.

Check your Expo SDK version

A lot of Expo Doctor problems come down to package versions not matching the Expo SDK you are using.

You can check your Expo version in package.json:

{
  "dependencies": {
    "expo": "~54.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

The exact version will depend on your project.

You can also run:

npx expo --version
Enter fullscreen mode Exit fullscreen mode

and:

npx expo config --type public
Enter fullscreen mode Exit fullscreen mode

The important thing is to know which Expo SDK your project is actually using before changing dependencies.

This matters because Expo packages are not completely independent of the SDK.

You cannot always just install the newest version of every package and expect everything to work together.

Fix packages that are on the wrong version

One of the most common Expo Doctor messages is related to package versions.

For example:

✖ Check that packages match versions required by installed Expo SDK
Enter fullscreen mode Exit fullscreen mode

Expo may tell you that some packages are expected to be on different versions.

If that happens, do not manually guess which version to install.

For Expo-managed projects, use:

npx expo install
Enter fullscreen mode Exit fullscreen mode

Expo can use your current SDK to install compatible package versions.

You can also check the project with:

npx expo install --check
Enter fullscreen mode Exit fullscreen mode

If it reports packages that are out of date, you can usually let Expo correct them with:

npx expo install --fix
Enter fullscreen mode Exit fullscreen mode

This is generally safer than doing something like:

npm install package-name@latest
Enter fullscreen mode Exit fullscreen mode

because the latest package version is not necessarily the version your current Expo SDK expects.

Do not blindly update everything

This is worth mentioning because it is an easy mistake to make.

Suppose Expo Doctor tells you that three packages have version mismatches.

You might think:

Fine, I'll just update everything.

Then you run something like:

npm update
Enter fullscreen mode Exit fullscreen mode

and suddenly you have five new errors.

You have now changed many things at once, which makes it harder to figure out what actually caused the problem.

If Expo is telling you that a package should be on a specific version, start with that package.

For example:

npx expo install react-native-screens
Enter fullscreen mode Exit fullscreen mode

rather than manually searching for the newest version and installing it.

Make one meaningful change at a time when possible.

It makes debugging much easier.

Check package.json for old dependencies

Another common situation is an old dependency that you no longer use.

Over time, a project can collect packages from old features, experiments, tutorials, or libraries you tried and later removed.

Your package.json might contain:

{
  "dependencies": {
    "some-old-package": "^1.2.3"
  }
}
Enter fullscreen mode Exit fullscreen mode

even though nothing in your application imports it anymore.

If Expo Doctor complains about that package, first check whether you still need it.

Search your project for:

some-old-package
Enter fullscreen mode Exit fullscreen mode

If there are no imports or references and you know you do not need it anymore, removing the dependency may be the correct fix.

For npm:

npm uninstall some-old-package
Enter fullscreen mode Exit fullscreen mode

For Yarn:

yarn remove some-old-package
Enter fullscreen mode Exit fullscreen mode

Then run Expo Doctor again.

Check for packages that are not compatible with your project

Sometimes the problem is not simply that a package is old.

A package may require native code or a setup that does not fit the way your Expo project is configured.

This becomes especially important when adding React Native libraries that were designed with bare React Native projects in mind.

You may install a package successfully with npm, but that does not automatically mean your Expo project is configured to use it correctly.

If Expo Doctor starts complaining immediately after adding a new library, that timing is useful information.

Try to remember:

What changed right before the error appeared?

If you just installed a package and Expo Doctor started failing, investigate that package first.

Check your Expo configuration

Expo Doctor can also complain about your project configuration.

Depending on your setup, this information may live in:

app.json
Enter fullscreen mode Exit fullscreen mode

or:

app.config.js
Enter fullscreen mode Exit fullscreen mode

or:

app.config.ts
Enter fullscreen mode Exit fullscreen mode

For example, your configuration might contain something like:

{
  "expo": {
    "name": "My App",
    "slug": "my-app"
  }
}
Enter fullscreen mode Exit fullscreen mode

If you recently changed your configuration, added a plugin, changed an Android or iOS setting, or installed a package that requires an Expo config plugin, check those changes carefully.

A configuration problem can sometimes look like a dependency problem because several parts of the Expo toolchain depend on the same project configuration.

Check Expo config plugins

Config plugins are another area that can cause confusion.

If you have something like:

{
  "expo": {
    "plugins": [
      "some-package"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

make sure that package is actually installed and that the plugin is valid for your current setup.

A common situation is:

  1. You install a package.
  2. You add its plugin to the Expo configuration.
  3. Later, you remove the package.
  4. The plugin entry stays behind.

Now Expo may still try to process something that no longer exists.

If you recently removed a native package, check app.json or your app config for leftover plugin entries.

Check for duplicate dependencies

Another useful thing to investigate is duplicate versions of the same package.

For example, your project might end up with different parts of the dependency tree using different versions of a React Native package.

You can inspect the dependency tree with npm:

npm ls
Enter fullscreen mode Exit fullscreen mode

Or check a specific package:

npm ls react-native-screens
Enter fullscreen mode Exit fullscreen mode

If you see multiple versions where you expected one, that can be a clue.

This does not automatically mean that multiple versions are wrong. Some projects legitimately have them.

The important part is to understand why they are there before trying to force everything onto one version.

Check your React Native version too

Expo SDK and React Native versions are closely related.

If you manually changed your React Native version, or upgraded one without properly upgrading the Expo SDK around it, Expo Doctor may start reporting compatibility problems.

For example, if your package.json contains:

{
  "dependencies": {
    "expo": "~54.0.0",
    "react-native": "..."
  }
}
Enter fullscreen mode Exit fullscreen mode

make sure those versions belong together.

If you are upgrading Expo, follow the Expo upgrade process instead of manually changing a bunch of package versions and hoping they line up afterward.

A partially upgraded project is often harder to fix than a project that was left alone.

Run expo-doctor again after fixing something

This sounds obvious, but it is an important part of the process.

After making a change, run:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

again.

You want to know whether the change actually fixed the problem.

For example:

Before:
✖ Check package versions

After:
✔ Check package versions
Enter fullscreen mode Exit fullscreen mode

Now you know that particular problem is gone.

If another check is still failing, you can work on that one separately.

This is much easier than making ten changes and running Expo Doctor once at the end.

What if Expo Doctor still fails?

If you have corrected the obvious dependency and configuration problems but Expo Doctor is still reporting an error, look at the exact check that is failing.

For example:

✖ Check for common project configuration problems
Enter fullscreen mode Exit fullscreen mode

is not enough information by itself.

Read the lines underneath it.

Expo Doctor normally provides additional information about what it found.

That information is much more useful than the ✖ itself.

Copy the complete section of the output, not just the first line.

Clear the cache if the project still behaves strangely

Clearing caches is not usually the first fix for an Expo Doctor warning.

Expo Doctor is checking your project configuration and dependencies, so a cache reset will not magically fix an incorrect package version.

However, if you have already fixed the reported problem and the project is still behaving as if the old state exists, clearing the Metro cache can help.

For Expo:

npx expo start -c
Enter fullscreen mode Exit fullscreen mode

This is particularly useful after changing dependencies, imports, or other files that Metro may have cached.

Just keep in mind that clearing Metro's cache and fixing Expo Doctor are two different things.

When reinstalling node_modules makes sense

If your package configuration looks correct but your installation itself seems broken, reinstalling dependencies can be worth trying.

Delete:

node_modules
Enter fullscreen mode Exit fullscreen mode

Then reinstall:

npm install
Enter fullscreen mode Exit fullscreen mode

Afterward:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

And if necessary:

npx expo start -c
Enter fullscreen mode Exit fullscreen mode

I would not delete your lockfile automatically.

Your package-lock.json or yarn.lock records the dependency versions that your project is using. Removing it can cause a completely new dependency tree to be installed, which may introduce more changes than you wanted.

If you specifically need to regenerate the lockfile, that is a different situation.

Be careful when upgrading an Expo project

If the reason for your Expo Doctor errors is that you are trying to move to a newer Expo SDK, do not treat it like a normal dependency update.

An Expo SDK upgrade can involve:

  • Expo packages
  • React Native
  • React
  • native dependencies
  • config plugins
  • Android configuration
  • iOS configuration
  • other packages tied to the SDK

If you upgrade only one or two pieces, you can end up with a project where everything is technically installed but the versions do not belong together.

If your goal is specifically to upgrade Expo, follow the upgrade process for the target SDK rather than trying to fix every warning individually.

A simple way to approach Expo Doctor

When I get an Expo Doctor error, I usually work through it in this order:

1. Run Expo Doctor 

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

2. Find the failed check

Do not worry about every line yet. Find the actual ✖ checks.

3. Read the details underneath

That is usually where the useful information is.

4. Check what changed recently

Did you:

  • install a package?
  • update Expo?
  • update React Native?
  • remove a package?
  • change app.json?
  • add a config plugin?
  • switch branches?

Recent changes are often the best clue.

5. Fix the smallest thing first

If a package version is wrong, fix that package.

If a plugin is left behind, remove it.

If a dependency is no longer needed, uninstall it.

6. Run Expo Doctor again 

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

Then see what remains.

This gives you a much cleaner debugging loop.

One example

Imagine you run:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

and get a dependency version warning.

You check package.json and notice that you manually installed a newer version of an Expo-related package a few days ago.

Instead of immediately reinstalling everything, you can try:

npx expo install
Enter fullscreen mode Exit fullscreen mode

or, if Expo identifies the package as needing a correction:

npx expo install --fix
Enter fullscreen mode Exit fullscreen mode

Then run:

npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

again.

If the check passes, you have your answer.

If it does not, you now have a smaller problem to investigate.

That is the part that makes debugging much easier: change something, test it, and use the new output to decide what to do next.

Final thoughts

Expo Doctor is there to help you find problems before they turn into much bigger issues.

The important thing is not to treat every warning as a reason to rebuild your entire project.

Start with the exact check that failed.

If it is a dependency problem, check the package versions.

If it is a configuration problem, check your Expo config.

If you recently installed or removed a package, investigate that change.

And if you are upgrading Expo, make sure you are upgrading the related dependencies together instead of manually mixing versions.

Most importantly, avoid making a dozen changes at once. When you do that, even if the error disappears, you have no idea which change actually fixed it.

If your Expo Doctor output is more complicated—especially when several checks fail at the same time—you can paste the full error into FixMyError and use it to break down what the output is actually telling you.

You can try it at https://www.fixmyerrorapp.com.

Top comments (0)