remix-run/remix · error · CliError

RMX_ROUTE_MAP_LOADER_FAILED

RMX_ROUTE_MAP_LOADER_FAILED

Error message

${message}

What it means

The route-map loader subprocess ran to completion but exited with a nonzero code. Its trimmed stderr becomes the error message (or the generic 'Route-map loader failed.' when stderr is empty), surfacing whatever crashed inside the loader.

Source

Thrown at packages/cli/src/lib/route-map.ts:131

    (resolve, reject) => {
      child.once('error', reject)
      child.once('close', (code, signal) => {
        resolve({ code, signal })
      })
    },
  )

  if (exitResult.signal != null) {
    throw routeMapLoaderSignal(exitResult.signal)
  }

  if (exitResult.code !== 0) {
    let message = stderr.trim()
    if (message.length === 0) {
      message = 'Route-map loader failed.'
    }

    throw routeMapLoaderFailed(message)
  }

  let parsed: unknown
  try {
    parsed = JSON.parse(stdout)
  } catch {
    throw routeMapLoaderInvalidJson()
  }

  return assertRawRouteTree(parsed)
}

function decorateRouteTree(
  rawTree: RawRouteTreeNode[],
  ownership: ControllerOwnership,
): RouteTreeNode[] {
  let subtreesByRouteName = new Map(
    ownership.subtrees.map((subtree) => [subtree.routeName, subtree]),

View on GitHub (pinned to 9696913134)

Solutions

1. Run the reported stderr message to ground the real failure
2. Directly import/run your routes.ts (or `remix routes`-style commands) to reproduce the crash
3. Fix the underlying exception in the app module the loader imports
4. If the message is empty, run with verbose/debug output to capture loader stderr

catch (error) {
  if (error instanceof Error && error.code === 'RMX_ROUTE_MAP_LOADER_FAILED') {
    // error.message is the loader's stderr; surface it to the user
  }
  throw error
}

When it happens

Trigger: The spawned route-map loader process throwing an unhandled exception or calling process.exit(nonzero) — e.g. a broken routes.ts, a failed import inside app code, or a runtime incompatibility.

Common situations: Syntax/runtime errors in app/routes.ts or modules it imports; using APIs unavailable to the loader's runtime; app code that throws at module load time.

Related errors

• RMX_ROUTE_MAP_LOADER_SIGNAL
• RMX_ROUTE_MAP_LOADER_INVALID_JSON
• hmr must be provided
• hmr requires watch mode
• Missing app/routes.ts path.

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