Troubleshooting

Fixing common issues with Expo Router setup.

Missing files or source maps in React Native DevTools

This can happen if your Chrome DevTools has exclusions within its ignore list. To fix the issue, use React Native DevTools:

1. Start the React Native DevTools by pressing J from the development server running in the terminal window
2. Open Settings by clicking the gear icon
3. Under Extensions, click Restore defaults and reload
4. Open Settings again, and go to Ignore List tab
5. Uncheck any exclusions for /node_modules/

EXPO_ROUTER_APP_ROOT not defined

If process.env.EXPO_ROUTER_APP_ROOT is not defined you'll see the following error:

This can happen when the Babel plugin expo-router/babel is not used in the project babel.config.js. You can try clearing the cache with:

Alternatively, you can circumvent this issue by creating an index.js file in the root of your project with the following contents:

import { registerRootComponent } from 'expo';
import { ExpoRoot } from 'expo-router';

// Must be exported or Fast Refresh won't update the context
export function App() {
  const ctx = require.context('./app');
  return <ExpoRoot context={ctx} />;
}

registerRootComponent(App);

Do not use this to change the root directory (app) as it won't account for usage in any other places.

require.context not enabled

This can happen when using a custom version of @expo/metro-config that does not enable context modules. Expo Router requires the project metro.config.js to use expo-router/metro as the default configuration. Delete the metro.config.js, or extend expo/metro-config. See Customizing metro for more information.

Missing back button

If you set up a modal or another screen that is expected to have a back button, then you'll need to add unstable_settings to the route's layout to ensure the initial route is configured. Initial routes are somewhat unique to mobile apps and fit awkwardly in the system — improvements pending.

export const unstable_settings = {
  initialRouteName: 'index',
};