remix-run/remix · error · Error

Missing app/routes.ts path.

Error message

Missing app/routes.ts path.

What it means

The route-map worker thread is invoked as `node load-route-map-worker.js <path-to-app/routes.ts>`; if argv[2] is missing or empty it cannot load the route config and exits. This is an internal invocation contract error, not a user config error.

Source

Thrown at packages/cli/src/lib/load-route-map-worker.ts:19

import * as process from 'node:process'
import { pathToFileURL } from 'node:url'

import type { RawRouteTreeNode } from './route-map.ts'

void run().catch((error: unknown) => {
  if (error instanceof Error) {
    process.stderr.write(`${error.message}\n`)
  } else {
    process.stderr.write(`${String(error)}\n`)
  }

  setExitCode(1)
})

async function run(): Promise<void> {
  let routesFile = process.argv[2]
  if (typeof routesFile !== 'string' || routesFile.length === 0) {
    throw new Error('Missing app/routes.ts path.')
  }

  let tree = await loadRawRouteTree(routesFile)
  process.stdout.write(JSON.stringify(tree))
}

async function loadRawRouteTree(routesFile: string): Promise<RawRouteTreeNode[]> {
  let routeModule: object = await import(pathToFileURL(routesFile).href)

  if (!('routes' in routeModule)) {
    throw new Error(`Route module ${routesFile} must export a named "routes" value.`)
  }

  return normalizeRouteGroup(routeModule.routes, [], new Map())
}

function normalizeRouteGroup(
  value: unknown,

View on GitHub (pinned to 9696913134)

Solutions

1. Do not run the worker directly; invoke the CLI command that spawns it (e.g. `remix routes` or dev/build)
2. If spawning programmatically, pass the absolute path to app/routes.ts as the second CLI argument
3. Reinstall/upgrade the CLI so the worker and spawner versions match

Example fix

# before
node node_modules/remix/cli/lib/load-route-map-worker.js
# after
npx remix routes

if (process.argv[2] == null || process.argv[2] === '') {
  console.error('usage: worker <app/routes.ts>')
  process.exit(1)
}

When it happens

Trigger: Spawning the worker without the routesFile argument or with an empty string; only happens if the spawning code in route-map.ts is broken or the worker script is run manually without args.

Common situations: Manually executing the worker file to debug route loading; a fork/spawn bug or version mismatch between the CLI and the worker bundle.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• Route-map loader returned an invalid tree.
• Route-map loader returned an invalid route node.
• Route-map loader returned a route node without a valid name.
• Route-map loader returned an unknown node kind for "${name}"
• Route-map loader returned invalid children for "${name}".

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