hashicorp/vagrant · error · Vagrant::Errors::CLIInvalidUsage

This command was not invoked properly. The help for this com

Error message

This command was not invoked properly. The help for this command is
available below.

%{help}

What it means

Raised by `vagrant box add` when the positional arguments after flags are empty or number more than two. The command accepts exactly one URL, or a box name plus a URL; argv[0] and argv[1] are consumed as name/URL, so anything else (including no arguments at all) is invalid usage and the help text is shown.

Source

Thrown at plugins/commands/box/command/add.rb:77

            o.on("--checksum CHECKSUM", String, "Checksum for the box") do |c|
              options[:checksum] = c
            end

            o.on("--checksum-type TYPE", String, "Checksum type (md5, sha1, sha256)") do |c|
              options[:checksum_type] = c.to_sym
            end

            o.on("--name BOX", String, "Name of the box") do |n|
              options[:name] = n
            end
          end

          # Parse the options
          argv = parse_options(opts)
          return if !argv
          if argv.empty? || argv.length > 2
            raise Vagrant::Errors::CLIInvalidUsage,
              help: opts.help.chomp
          end

          url = argv[0]
          if argv.length == 2
            options[:name] = argv[0]
            url = argv[1]
          end

          @env.action_runner.run(Vagrant::Action.action_box_add, {
            box_url: url,
            box_name: options[:name],
            box_provider: options[:provider],
            box_architecture: options[:architecture],
            box_version: options[:version],
            box_checksum_type: options[:checksum_type],
            box_checksum: options[:checksum],
            box_clean: options[:clean],

View on GitHub (pinned to 35f3160f4a)

Solutions

Provide a box shorthand or URL: `vagrant box add ubuntu/jammy`
To set an explicit name use two arguments: `vagrant box add my-ubuntu https://example.com/ubuntu.box`
Run `vagrant box add --help` to review checksum/name/clean flags

Example fix

# before
vagrant box add

# after
vagrant box add ubuntu/jammy
# or with an explicit name
vagrant box add my-ubuntu https://example.com/ubuntu.box

Defensive patterns

Strategy: validation

Validate before calling

# bash: box add takes 1 or 2 positionals (url, or name+url)
if [ $# -lt 1 ] || [ $# -gt 2 ]; then
  vagrant box add --help; exit 1
fi
vagrant box add "$@"

Prevention

Default to the shorthand form: `vagrant box add ubuntu/jammy`
Use the --name flag instead of the two-positional form in scripts
Run `vagrant box add --help` to review checksum options for reproducible adds

When it happens

Trigger: `vagrant box add` with no arguments; `vagrant box add name url extra`; any invocation where parse_options leaves zero or 3+ positional words.

Common situations: Assuming a file picker or interactive prompt; forgetting the box shorthand/URL; pasting multiple boxes into one command.

Related errors

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/1a5753bf6c5e04d2. Report an issue: GitHub.