Troubleshooting

Fixing common issues with Expo Router setup.

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',
};