remix-run/remix · error · CliError

RMX_ROUTE_MAP_LOADER_FAILED

RMX_ROUTE_MAP_LOADER_FAILED

Error message

Route-map loader failed

What it means

The Remix CLI could not execute the route-map loader used to read your route configuration. The CLI runs app/routes.ts through a loader subprocess to extract the exported `routes` value; if that subprocess fails to start or exits abnormally, this error is thrown. It is a CLI-side configuration error, not a runtime error in your app.

Source

Thrown at packages/cli/src/lib/errors.ts:108

    title: 'Missing target directory',
    fix: 'Pass a target directory, for example `remix new my-remix-app`.',
  },
  projectRootNotFound: {
    code: 'RMX_PROJECT_ROOT_NOT_FOUND',
    title: 'Could not find a project root',
    fix: 'Run this command inside a Remix project.',
  },
  remixConfigNotFound: {
    code: 'RMX_CONFIG_NOT_FOUND',
    title: 'Remix configuration not found',
    fix: 'Check the --config path and try again.',
  },
  remoteSkillDataMissing: {
    code: 'RMX_REMOTE_SKILL_DATA_MISSING',
    title: 'Could not find remote Remix skill data',
  },
  routeMapLoaderFailed: {
    code: 'RMX_ROUTE_MAP_LOADER_FAILED',
    title: 'Route-map loader failed',
    fix: 'Check app/routes.ts and make sure it exports a named `routes` value with a valid route map.',
  },
  routeMapLoaderInvalidJson: {
    code: 'RMX_ROUTE_MAP_LOADER_INVALID_JSON',
    title: 'Route-map loader returned invalid JSON',
    fix: 'Check app/routes.ts and make sure route-map loading does not write extra output.',
  },
  routeMapLoaderSignal: {
    code: 'RMX_ROUTE_MAP_LOADER_SIGNAL',
    title: 'Route-map loader exited from a signal',
    fix: 'Check app/routes.ts for side effects or runtime issues and try again.',
  },
  routeOwnerPlanUnresolved: {
    code: 'RMX_ROUTE_OWNER_PLAN_UNRESOLVED',
    title: 'Could not resolve a route owner plan',
  },
  routesFileNotFound: {

View on GitHub (pinned to 9696913134)

Solutions

1. Check app/routes.ts exists and exports `export const routes` (or a route config array/map).
2. Remove top-level side effects or failing imports from app/routes.ts (e.g. code needing env vars or DOM APIs).
3. Run `npx tsx app/routes.ts` (or equivalent) locally to confirm the file loads without throwing.
4. Verify you are running the CLI from the app root so app/routes.ts resolves.

Example fix

// before
// app/routes.ts
export default routes // no named export

// after
// app/routes.ts
export const routes = [
  { path: '/', file: 'routes/index.tsx' },
] satisfies RouteConfig

import { access } from 'node:fs/promises'

async function routesFileValid(dir: string) {
  try {
    await access(path.join(dir, 'app/routes.ts'))
    return true
  } catch {
    return false
  }
}

try {
  await runRouteMapCommand()
} catch (error) {
  if (error instanceof CliError && error.code === 'RMX_ROUTE_MAP_LOADER_FAILED') {
    // guide user to fix app/routes.ts
  }
  throw error
}

When it happens

Trigger: Running CLI commands (e.g. `remix routes` or dev/build flows that need the route map) when app/routes.ts is missing, does not export a named `routes` value, or throws/segfaults during execution of the loader subprocess.

Common situations: A fresh non-Remix directory, an app/routes.ts that imports modules failing at load time (missing env vars, top-level side effects), or renaming/removing the `routes` export during a refactor.

Related errors

• Route module ${routesFile} must export a named "routes" valu
• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof
• expected promise to resolve, but it rejected with: ${stringi
• expected promise to reject, but it resolved with: ${stringif

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/3354e0625f21877e. Report an issue: GitHub.