If you work with Expo long enough, you will probably run into expo-doctor.
You run:
npx expo-doctor
and instead of everything being green, you get something like:
✖ Check Expo config
✖ Check dependencies
✖ Check package versions
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
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
That is very different from:
✖ Check for common project configuration problems
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"
}
}
The exact version will depend on your project.
You can also run:
npx expo --version
and:
npx expo config --type public
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
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
Expo can use your current SDK to install compatible package versions.
You can also check the project with:
npx expo install --check
If it reports packages that are out of date, you can usually let Expo correct them with:
npx expo install --fix
This is generally safer than doing something like:
npm install package-name@latest
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
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
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"
}
}
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
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
For Yarn:
yarn remove some-old-package
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
or:
app.config.js
or:
app.config.ts
For example, your configuration might contain something like:
{
"expo": {
"name": "My App",
"slug": "my-app"
}
}
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"
]
}
}
make sure that package is actually installed and that the plugin is valid for your current setup.
A common situation is:
- You install a package.
- You add its plugin to the Expo configuration.
- Later, you remove the package.
- 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
Or check a specific package:
npm ls react-native-screens
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": "..."
}
}
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
again.
You want to know whether the change actually fixed the problem.
For example:
Before:
✖ Check package versions
After:
✔ Check package versions
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
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
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
Then reinstall:
npm install
Afterward:
npx expo-doctor
And if necessary:
npx expo start -c
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
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
Then see what remains.
This gives you a much cleaner debugging loop.
One example
Imagine you run:
npx expo-doctor
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
or, if Expo identifies the package as needing a correction:
npx expo install --fix
Then run:
npx expo-doctor
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.