remix-run/react-router · error · Error

React Router config loading requires Vite's __config_loader

Error message

React Router config loading requires Vite's __config_loader environment to be runnable.

What it means

Thrown in vite-runner.ts after creating a dev server with an `__config_loader` environment: the code asserts the environment is a runnable dev environment via vite.isRunnableDevEnvironment(). If it isn't (e.g. the environment was overridden by another plugin or Vite config to a non-runnable type), React Router cannot execute the user's react-router.config.ts module via the module runner, so it errors out and closes the dev server.

Source

Thrown at packages/react-router-dev/vite/vite-runner.ts:66

    configFile: false,
    envDir: false,
    plugins: [],
    environments: {
      __config_loader: {
        consumer: "server",
        dev: {
          createEnvironment: (name, config, context) =>
            vite.createRunnableDevEnvironment(name, config),
        },
      },
    },
  });

  const environment = devServer.environments.__config_loader;

  if (!vite.isRunnableDevEnvironment(environment)) {
    await devServer.close();
    throw new Error(
      "React Router config loading requires Vite's __config_loader environment to be runnable.",
    );
  }

  return { devServer, environment, runner: environment.runner };
}

View on GitHub (pinned to 1fd704a7da)

Solutions

1. Align Vite version with the peerDependency range of @react-router/dev (check package.json peerDeps).
2. Remove or audit any vite.config customization of `environments` or `createEnvironment`.
3. Disable third-party plugins one by one to find one that overrides the environment.
4. Update @react-router/dev to the latest patch that targets your Vite major.

Example fix

// vite.config.ts — before (overrides the environment React Router depends on)
export default defineConfig({ environments: { __config_loader: { consumer: 'client', dev: { createEnvironment: customEnvFactory } } } });
// after — let React Router own the __config_loader environment
export default defineConfig({ plugins: [reactRouter()] });

import * as vite from 'vite';
const satisfies = typeof vite.createRunnableDevEnvironment === 'function' && typeof vite.isRunnableDevEnvironment === 'function';
if (!satisfies) throw new Error('Installed Vite does not support runnable dev environments; align with @react-router/dev peer range.');

function viteSupportsRunnableEnv(vite: typeof import('vite')): boolean {
  return typeof vite.createRunnableDevEnvironment === 'function' && typeof vite.isRunnableDevEnvironment === 'function';
}

When it happens

Trigger: A plugin or user vite.config overrides `environments.__config_loader` or replaces `createEnvironment` so it no longer returns a runnable environment. A Vite version where createRunnableDevEnvironment is unavailable or behaves differently. Environment API mismatch between Vite and @react-router/dev.

Common situations: Vite major upgrade that changed the Environment API (consumer/server split). A custom plugin that globally overrides createEnvironment. Pinning to an incompatible Vite version outside @react-router/dev's peer range.

Related errors

• React Router Vite plugin not found in Vite config
• Custom Vite manifest paths are not supported
• The React Router Vite plugin requires the use of a Vite conf
• Prerender: Failed to start Vite preview server
• Prerender: No resolved URL is available from the Vite previe

AI-assisted analysis of remix-run/react-router@1fd704a7da (2026-08-12). Data as JSON: /api/errors/288d0edf90795db0. Report an issue: GitHub.