remix-run/remix · error · Error

Route-map loader returned an unknown node kind for "${name}"

Error message

Route-map loader returned an unknown node kind for "${name}".

What it means

Each route node has a discriminator `kind` that must be 'group' or 'route'. An unknown kind means the payload schema doesn't match what the validating code expects.

Source

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

  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}".`)
  }

  if (kind === 'group') {
    return {
      children: children.map((child) => assertRawRouteTreeNode(child)),
      key,
      kind,
      name,
    }
  }

  let method = Reflect.get(value, 'method')
  let pattern = Reflect.get(value, 'pattern')

View on GitHub (pinned to 9696913134)

Solutions

1. Ensure all remix packages are the same version and reinstall
2. Update mocks to use only 'group' or 'route' kinds
3. Check release notes if a newer worker added kinds your validator doesn't know — upgrade the consuming package too

const kinds = new Set(['group', 'route'])
tree.every(n => kinds.has((n as any).kind))

function isKnownKind(n: unknown): n is { kind: 'group' | 'route' } {
  let k = (n as any)?.kind
  return k === 'group' || k === 'route'
}

When it happens

Trigger: A node whose `kind` is anything other than 'group'/'route' (e.g. 'layout', 'index', or undefined) reaching assertRawRouteTreeNode.

Common situations: Worker binary from a newer/older remix emitting new node kinds; mocked trees with made-up kind values.

Related errors

• Route-map loader returned an invalid route node.
• Route-map loader returned a route node without a valid 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/7ff94231e212eeb1. Report an issue: GitHub.