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 remove` when no positional argument is given or more than two are supplied. Exactly one argument (the box name) is expected; a second positional argument is a deprecated way to name the provider (a warning is printed for it), so anything beyond that is a hard usage error.

Source

Thrown at plugins/commands/box/command/remove.rb:54

            o.on("--all", "Remove all available versions of the box") do |a|
              options[:all] = a
            end

            o.on("--all-providers", "Remove all providers within a version of the box") do |a|
              options[:all_providers] = a
            end

            o.on("--all-architectures", "Remove all architectures within a provider a version of the box") do |a|
              options[:all_architectures] = a
            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

          if argv.length == 2
            # @deprecated
            @env.ui.warn("WARNING: The second argument to `vagrant box remove`")
            @env.ui.warn("is deprecated. Please use the --provider flag. This")
            @env.ui.warn("feature will stop working in the next version.")
            options[:provider] = argv[1]
          end

          @env.action_runner.run(Vagrant::Action.action_box_remove, {
            box_name:     argv[0],
            box_architecture: options[:architecture],
            box_provider: options[:provider],
            box_version:  options[:version],
            force_confirm_box_remove: options[:force],
            box_remove_all_versions: options[:all],

View on GitHub (pinned to 35f3160f4a)

Solutions

Give the box name: `vagrant box remove ubuntu/jammy`
Select the provider with the flag, not a second positional: `vagrant box remove ubuntu/jammy --provider virtualbox`
Run `vagrant box remove --help` for --all-providers / --all-architectures / --box-version flags

Example fix

# before
vagrant box remove

# after
vagrant box remove ubuntu/jammy --provider virtualbox

Defensive patterns

Strategy: validation

Validate before calling

# bash: box remove takes exactly 1 positional (2 tolerated, deprecated)
if [ $# -lt 1 ] || [ $# -gt 1 ]; then
  vagrant box remove --help; exit 1
fi
vagrant box remove "$1" --provider "$PROVIDER"

Prevention

Use --provider instead of the deprecated second positional argument
Script removals with the box name plus --provider/--box-version flags only
List boxes first (`vagrant box list`) to confirm the exact name spelling

When it happens

Trigger: `vagrant box remove` with no arguments; `vagrant box remove name provider extra`; any invocation where argv is empty or longer than two words.

Common situations: Forgetting the box name; trying to remove by URL; combining old positional-provider syntax with the --provider flag and passing three words.

Related errors

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