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

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

In the RSC Framework-mode Vite plugin, when running the default dev server (viteCommand 'serve' and server.middlewareMode falsy), the plugin validates that the React Router 'basename' is compatible with Vite's 'base' option: if base is set and basename is not '/', basename must start with base. The default Vite dev server serves all assets and the app under 'base', so a basename without that prefix would route to paths the dev server can never reach.

Solutions

Prefix basename with base, e.g. base "/my-app/" + basename "/my-app/dashboard"
Drop the React Router basename and let vite base drive the prefix alone
Run dev through a custom server or Vite middlewareMode, where this default-dev-server constraint does not apply

Example fix

// before
// vite.config.ts
export default defineConfig({ base: "/my-app/" });
// react-router.config.ts
export default { basename: "/dashboard" };

// after
// react-router.config.ts
export default { basename: "/my-app/dashboard" };

Defensive patterns

Strategy: validation

Validate before calling

// fail fast before starting the dev server
const viteBase = "/my-app/";          // value from vite.config.ts
const basename = "/my-app/dashboard"; // value from react-router.config.ts
if (viteBase && basename !== "/" && !basename.startsWith(viteBase)) {
  throw new Error(`basename '${basename}' must start with vite base '${viteBase}' in dev`);
}

Prevention

Derive basename from base in one place (e.g. basename: `${base}app`) so they can't drift
Document the base/basename relationship in the repo README for new contributors
Prefer relying on vite base alone unless basename is truly required

When it happens

Trigger: Running 'react-router dev' with vite.config.ts base: "/my-app/" and react-router.config.ts basename: "/dashboard" — basename is set, non-'/', does not start with base, and the dev server is the default (non-middlewareMode) one.

Common situations: Deploying under a subpath (GitHub Pages, shared hosting) and setting both vite base and router basename independently; migrating an app that only used basename and later adding vite base; RSC Framework templates combined with a repo subpath.

Related errors

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

Appendix: 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 6beaca3952)