nodejs/node · error · Error

Unknown positional argument: ${extra}

Error message

Unknown positional argument: ${extra}

What it means

After option parsing, npm compares leftover positional arguments against the count the command declares (constructor.positionals). Any positional beyond that count is treated as unknown and throws, naming the first extra. This guards against typos and wrong-command usage.

Source

Thrown at deps/npm/lib/base-cmd.js:424

        }
      }
    }

    // Remove warnings for unknown positionals that were actually consumed as flag values by command-specific definitions (e.g., --id <value> where --id is command-specific)
    const remainsSet = new Set(remains)
    for (const unknownPos of this.npm.config.getUnknownPositionals()) {
      if (!remainsSet.has(unknownPos)) {
        // This value was consumed as a flag value, not truly a positional
        this.npm.config.removeUnknownPositional(unknownPos)
      }
    }

    // Warn about extra positional arguments beyond what the command expects
    const expectedPositionals = this.constructor.positionals
    if (expectedPositionals !== null && remains.length > expectedPositionals) {
      const extraPositionals = remains.slice(expectedPositionals)
      for (const extra of extraPositionals) {
        throw new Error(`Unknown positional argument: ${extra}`)
      }
    }

    this.npm.config.logWarnings()
  }

  async exec () {
    // This method should be overridden by commands
    // Subcommand routing is handled in npm.js #exec
  }
}

module.exports = BaseCommand

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Count your positionals against the command signature in `npm help <command>` and remove the named extra
2. If an extra was meant as a flag value, attach it with `=` or add the missing flag (e.g. --opt=value)
3. Quote multi-word single arguments so the shell does not split them

Example fix

# before
npm cache verify /tmp/extra

# after
npm cache verify

// Validate positional count against the command's documented arity before running
function validatePositionals(cmd, positionals, expected) {
  if (expected !== null && positionals.length > expected) {
    throw new Error(`${cmd} expects at most ${expected} positional(s), got ${positionals.length}`)
  }
}

function withinPositionalLimit(args, limit) {
  return limit === null || args.length <= limit
}

When it happens

Trigger: Passing more positional arguments than the command accepts, e.g. a single-positional command given two; values that were meant as flag values but parsed as positionals because the flag was omitted.

Common situations: Quoting that splits one arg into many; wrong command chosen for the intent; trailing junk from a variable expansion ($UNSET expanding to nothing or extra tokens).

Related errors

• Expected a single path argument.
• %s: error: no build_file
• Not enough arguments
• Need one argument which is the .gypi file to read.
• too many options passed

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/714aeefd66dfcb47. Report an issue: GitHub.