remix-run/remix · error · UsageError

RMX_UNKNOWN_ARGUMENT

RMX_UNKNOWN_ARGUMENT

Error message

Unknown argument: ${argument}

What it means

Thrown by parseArgs when a flag that is registered as a boolean option is given an inline value with `=` (e.g. `--flag=value`). Boolean specs never accept values, so `--bool=false` is treated as an unknown argument form rather than being silently mis-parsed.

Source

Thrown at packages/cli/src/lib/parse-args.ts:60

    [keyof definitions, ParseArgsOptionSpec]
  >) {
    values[key] = (
      spec.type === 'boolean' ? false : undefined
    ) as ParsedArgsValues<definitions>[typeof key]
    specsByFlag.set(spec.flag, { key, spec })
  }

  for (let index = 0; index < argv.length; index++) {
    let arg = argv[index]!
    let equalsIndex = arg.indexOf('=')
    let flag = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex)
    let inlineValue = equalsIndex === -1 ? undefined : arg.slice(equalsIndex + 1)
    let resolved = specsByFlag.get(flag)

    if (resolved != null) {
      if (resolved.spec.type === 'boolean') {
        if (inlineValue !== undefined) {
          throw unknownArgument(arg)
        }

        values[resolved.key] = true as ParsedArgsValues<definitions>[typeof resolved.key]
        continue
      }

      if (inlineValue !== undefined) {
        if (inlineValue.length === 0) {
          throw missingOptionValue(flag)
        }

        values[resolved.key] = inlineValue as ParsedArgsValues<definitions>[typeof resolved.key]
        continue
      }

      let next = argv[index + 1]
      if (next == null || next.length === 0 || next.startsWith('-')) {
        throw missingOptionValue(flag)

View on GitHub (pinned to 9696913134)

Solutions

1. Drop the `=value` part and pass the bare flag (e.g. `--flag` instead of `--flag=true`)
2. Check the command's flag definitions to confirm which flags are boolean
3. If you need value-taking behavior, use a flag defined with a value type

Example fix

# before
remix create my-app --force=true
# after
remix create my-app --force

const BOOL_FLAGS = new Set(['force', 'verbose'])
const args = process.argv.slice(2)
for (const arg of args) {
  if (arg.startsWith('--') && arg.includes('=')) {
    const [name] = arg.slice(2).split('=')
    if (BOOL_FLAGS.has(name)) throw new Error(`Boolean flag --${name} must not have a value`) 
  }
}

const isBooleanFlagWithInlineValue = (arg: string, boolFlags: Set<string>): boolean =>
  arg.startsWith('--') && arg.includes('=') && boolFlags.has(arg.slice(2).split('=')[0])

When it happens

Trigger: Calling the CLI arg parser with `--someBool=true` or `--someBool=anything` where `someBool` is defined in the spec with `type: 'boolean'`.

Common situations: Users accustomed to `--flag=false` syntax from other CLI tools passing it to a Remix CLI command whose flag is boolean-only.

Related errors

• RMX_UNEXPECTED_ARGUMENT
• --config requires a value.
• Unknown command: assets ${command}
• `remix assets inspect` requires a URL or file path.
• Unknown command: db ${command}

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