moeru-ai/airi · error · Error

Unsupported route path

Error message

Unsupported route path "${routePath}". Route paths must start with "/".

What it means

Thrown by the capture.ts CLI guard when the --route value does not start with '/'. The value is passed straight to captureBrowserRoots as a browser route path, and the check enforces router-absolute paths; relative fragments, bare route names, or full URLs all fail. Default is '/docs/setup-and-use' when the flag is omitted.

Solutions

Pass an absolute app path: pnpm capture -- --route /chat.
Normalize in wrappers: --route "/${ROUTE#/}" to guarantee the leading slash.
If starting from a URL, strip the origin first (new URL(u).pathname).
Ensure a value actually follows --route on the command line.

Example fix

# before
pnpm capture -- --route chat # throws: Route paths must start with "/"

# after
pnpm capture -- --route /chat

Defensive patterns

Strategy: validation

Validate before calling

// Normalize route lists before invoking capture.ts:
const routes = ['/chat', 'settings'].map(r => r.startsWith('/') ? r : `/${r}`)
for (const route of routes) {
  if (!route.startsWith('/')) throw new Error(`Bad route: ${route}`)
}

Type guard

const isAbsoluteRoutePath = (value: string): boolean => value.startsWith('/')
// use: routes.filter(isAbsoluteRoutePath) or assert before exec

Prevention

Store route names with the leading slash in route registries/configs.
When copying from a URL, pass new URL(u).pathname, not the full URL.
Always provide a value after --route on the command line.

When it happens

Trigger: Running with --route chat, --route ./chat, or --route https://localhost:3000/chat; building the flag from a routes list that stores names without the leading slash; quoting issues that prepend whitespace; a missing value after --route yielding undefined.

Common situations: CI capture jobs iterating over app routes stored without leading slashes; copying a URL instead of its path; wrapper scripts interpolating variables that are sometimes empty or relative.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of moeru-ai/airi@677329427f (2026-08-18). Data as JSON: /api/errors/e701cd12714972c0. Report an issue: GitHub.

Appendix: source

Thrown at packages/scenarios-stage-tamagotchi-browser/scripts/capture.ts:63

    speed: avifSpeed,
  })

  await writeFile(derivedFilePath, avifBuffer)
  await rm(artifact.filePath, { force: true })

  return {
    ...artifact,
    filePath: derivedFilePath,
    format: 'avif',
  }
}

if (!['png', 'avif'].includes(requestedFormat)) {
  throw new Error(`Unsupported capture format "${requestedFormat}". Expected "png" or "avif".`)
}

if (!routePath?.startsWith('/')) {
  throw new Error(`Unsupported route path "${routePath}". Route paths must start with "/".`)
}

if (outputDirFlagIndex >= 0 && !argv[outputDirFlagIndex + 1]) {
  throw new Error('Missing value for --output-dir.')
}

if (settleMsFlagIndex >= 0 && !argv[settleMsFlagIndex + 1]) {
  throw new Error('Missing value for --settle-ms.')
}

if (avifMaxWidthFlagIndex >= 0 && !argv[avifMaxWidthFlagIndex + 1]) {
  throw new Error('Missing value for --avif-max-width.')
}

if (avifQualityFlagIndex >= 0 && !argv[avifQualityFlagIndex + 1]) {
  throw new Error('Missing value for --avif-quality.')
}

View on GitHub (pinned to 677329427f)