remix-run/remix · error · CliError

RMX_UNEXPECTED_ARGUMENT

RMX_UNEXPECTED_ARGUMENT

Error message

Unexpected extra argument

What it means

The command received more positional arguments than it accepts. Argument parsing rejects extras rather than silently ignoring them, and the fix hint points to --help for the expected signature.

Source

Thrown at packages/cli/src/lib/errors.ts:142

    title: 'Could not resolve a route owner plan',
  },
  routesFileNotFound: {
    code: 'RMX_ROUTES_FILE_NOT_FOUND',
    title: 'Could not find app/routes.ts',
    fix: 'Run this command inside a Remix app that has app/routes.ts.',
  },
  targetDirectoryNotEmpty: {
    code: 'RMX_TARGET_DIRECTORY_NOT_EMPTY',
    title: 'Target directory is not empty',
    fix: 'Re-run with --force to continue.',
  },
  targetPathNotDirectory: {
    code: 'RMX_TARGET_PATH_NOT_DIRECTORY',
    title: 'Target path is not a directory',
    fix: 'Choose a directory path for the new app target.',
  },
  unexpectedExtraArgument: {
    code: 'RMX_UNEXPECTED_ARGUMENT',
    title: 'Unexpected extra argument',
    fix: 'Remove the extra argument or run the command with --help.',
  },
  unknownArgument: {
    code: 'RMX_UNKNOWN_ARGUMENT',
    title: 'Unknown argument',
    fix: 'Run the command with --help to see supported arguments.',
  },
  unknownCommand: {
    code: 'RMX_UNKNOWN_COMMAND',
    title: 'Unknown command',
    fix: 'Run `remix help` to see available commands.',
  },
  unknownCompletionShell: {
    code: 'RMX_UNKNOWN_COMPLETION_SHELL',
    title: 'Unknown completion shell',
    fix: 'Run `remix completion bash` or `remix completion zsh`.',
  },

View on GitHub (pinned to 9696913134)

Solutions

1. Remove the extra argument so only the accepted count remains.
2. Run the command with --help to see the expected positional signature.
3. Quote globs/variables (`"$DIR"`) so they don't expand into extra arguments.

Example fix

# before
remix init my-app extra

# after
remix init my-app

// Validate argument count before invoking
let positional = args.filter((a) => !a.startsWith('-'))
if (positional.length > 1) {
  // reject before calling the CLI
}

try {
  run(args)
} catch (error) {
  if (error.code === 'RMX_UNEXPECTED_ARGUMENT') {
    // drop extras, print --help
  }
}

When it happens

Trigger: Passing two operands to a command taking one (e.g. `remix init a b`), or trailing shell-expanded values unintentionally becoming extra arguments.

Common situations: Unquoted globs expanding into multiple arguments, copy-pasting a command from docs with placeholder text left in, or assuming a command takes multiple targets.

Related errors

• --config requires a value.
• Unknown command: assets ${command}
• `remix assets inspect` requires a URL or file path.
• Unknown command: db ${command}
• Options --step and --to are mutually exclusive

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