remix-run/remix · error · Error

Route-map loader returned an invalid route node.

Error message

Route-map loader returned an invalid route node.

What it means

Each element of the worker's route tree must be a non-null object. This is the first shape assertion on every node; failing means the payload is structurally corrupt rather than a config typo.

Source

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

      kind: 'directory',
      path: directory.directoryPath,
    }
  }

  throw routeOwnerPlanUnresolved(rawNode.name)
}

function assertRawRouteTree(value: unknown): RawRouteTreeNode[] {
  if (!Array.isArray(value)) {
    throw new Error('Route-map loader returned an invalid tree.')
  }

  return value.map((entry) => assertRawRouteTreeNode(entry))
}

function assertRawRouteTreeNode(value: unknown): RawRouteTreeNode {
  if (typeof value !== 'object' || value == null) {
    throw new Error('Route-map loader returned an invalid route node.')
  }

  let key = Reflect.get(value, 'key')
  let name = Reflect.get(value, 'name')
  let kind = Reflect.get(value, 'kind')
  let children = Reflect.get(value, 'children')

  if (typeof key !== 'string' || typeof name !== 'string') {
    throw new Error('Route-map loader returned a route node without a valid name.')
  }

  if (kind !== 'group' && kind !== 'route') {
    throw new Error(`Route-map loader returned an unknown node kind for "${name}".`)
  }

  if (!Array.isArray(children)) {
    throw new Error(`Route-map loader returned invalid children for "${name}".`)
  }

View on GitHub (pinned to 9696913134)

Solutions

1. Align remix package versions and reinstall node_modules
2. Regenerate real worker output instead of hand-writing fixtures
3. Report upstream if it reproduces with a clean install

if (!Array.isArray(tree) || tree.some(n => typeof n !== 'object' || n === null)) {
  throw new Error('malformed tree')
}

function isNode(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null
}

When it happens

Trigger: An entry in the tree array is null, a string, a number, or undefined — typically from a mismatched worker version or a hand-crafted/mocked payload.

Common situations: Version skew between CLI packages after a partial upgrade; tests stubbing the worker with `[]` containing primitives.

Related errors

• 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}".
• Route-map loader returned an invalid route leaf for "${name}
• Missing app/routes.ts path.

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