remix-run/react-router · error · Error

When using the React Router `basename` and the Vite `base` c

Error message

When using the React Router `basename` and the Vite `base` config, the `basename` config must begin with `base` for the default Vite dev server.

What it means

Thrown in the RSC plugin config hook during `serve` (dev) when both Vite's `base` and React Router's `basename` are set, basename is not '/', the dev server is not in middleware mode, and basename does not start with base. The default Vite dev server serves assets under `base`, so a basename that doesn't include it would break routing/asset resolution.

Source

Thrown at packages/react-router-dev/vite/rsc/plugin.ts:194

            if (errors.length) {
              return `RSC Framework Mode does not currently support the following React Router config:\n${errors.map((x) => ` - ${x}`).join("\n")}\n`;
            }
          },
        });
        configLoader = await configLoaderPromise;

        const configResult = await configLoader.getConfig();
        if (!configResult.ok) throw new Error(configResult.error);
        updateConfig(configResult.value);

        if (
          viteUserConfig.base &&
          config.basename !== "/" &&
          viteCommand === "serve" &&
          !viteUserConfig.server?.middlewareMode &&
          !config.basename.startsWith(viteUserConfig.base)
        ) {
          throw new Error(
            "When using the React Router `basename` and the Vite `base` config, " +
              "the `basename` config must begin with `base` for the default " +
              "Vite dev server.",
          );
        }

        const vite = await import("vite");
        logger = vite.createLogger(viteUserConfig.logLevel, {
          prefix: "[react-router]",
        });

        entries = await resolveRSCEntryFiles({
          reactRouterConfig: config,
        });

        // Async import here to avoid CJS warnings on the console
        let viteNormalizePath = (await import("vite")).normalizePath;
        let optimizeDepsEntries = getOptimizeDepsEntries({

View on GitHub (pinned to 1fd704a7da)

Solutions

1. Make React Router `basename` begin with the Vite `base`, e.g. base '/app/' and basename '/app/dashboard'.
2. Or set basename to '/' (the default) and let base handle the prefix.
3. Or move the dev server into middleware mode (server.middlewareMode: true) to bypass the default-server constraint.
4. Double-check trailing slashes — base '/app' and basename '/application' will fail since '/application' does not start with '/app' as intended only if you meant '/app/...'.

Example fix

// react-router.config.ts + vite.config.ts
// before
// vite.config.ts: base: '/app/'
// react-router.config.ts: basename: '/dashboard/'
// after
// react-router.config.ts: basename: '/app/dashboard/'

// in a prebuild script
import viteUserConfig from './vite.config';
import rrConfig from './react-router.config';
const base = viteUserConfig.base; const basename = rrConfig.basename;
if (base && basename && basename !== '/' && !basename.startsWith(base)) {
  throw new Error(`basename '${basename}' must start with base '${base}'`);
}

function basenameCompatibleWithBase(base: string | undefined, basename: string | undefined): boolean {
  if (!base || !basename || basename === '/') return true;
  return basename.startsWith(base);
}

When it happens

Trigger: vite.config.ts sets `base: '/app/'` while react-router.config.ts sets `basename: '/dashboard/'` (or any basename not prefixed by the base). Conditions: viteUserConfig.base truthy, config.basename !== '/', viteCommand === 'serve', no server.middlewareMode, !config.basename.startsWith(viteUserConfig.base).

Common situations: Deploying behind a path prefix (base) and also namespacing the app under a different basename. Mismatched trailing slashes (base '/app', basename '/app') where startsWith is technically true but couples are easy to get wrong. Copying a config that worked without base into a subpath deployment.

Related errors

• The "@vitejs/plugin-rsc" plugin should be placed after the R
• ${configResult.error}
• Cannot handle enhanced server action without decodeReply and
• Cannot handle form actions without a decodeAction function
• React Router presets must have a `name` property defined.

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