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

An invalid option was specified. The help for this command i

Error message

An invalid option was specified. The help for this command
is available below.

%{help}

What it means

Usage error from a v2 plugin command (which includes all modern built-in commands): OptionParser raised InvalidOption, MissingArgument, or AmbiguousOption while parsing argv, and parse_options converts it to CLIInvalidOptions with the command's help embedded as %{help} (lib/vagrant/plugin/v2/command.rb:67). It aborts the command before any machine is touched.

Source

Thrown at lib/vagrant/plugin/v2/command.rb:67

          ENV["POSIXLY_CORRECT"] = nil

          # Creating a shallow copy of the arguments so the OptionParser
          # doesn't destroy the originals.
          argv = @argv.dup

          # Default opts to a blank optionparser if none is given
          opts ||= Vagrant::OptionParser.new

          # Add the help option, which must be on every command.
          opts.on_tail("-h", "--help", "Print this help") do
            safe_puts(opts.help)
            return nil
          end

          opts.parse!(argv)
          return argv
        rescue OptionParser::InvalidOption, OptionParser::MissingArgument, OptionParser::AmbiguousOption
          raise Errors::CLIInvalidOptions, help: opts.help.chomp
        end

        # Yields a VM for each target VM for the command.
        #
        # This is a convenience method for easily implementing methods that
        # take a target VM (in the case of multi-VM) or every VM if no
        # specific VM name is specified.
        #
        # @param [String] name The name of the VM. Nil if every VM.
        # @param [Hash] options Additional tweakable settings.
        # @option options [Symbol] :provider The provider to back the
        #   machines with. All machines will be backed with this
        #   provider. If none is given, a sensible default is chosen.
        # @option options [Boolean] :reverse If true, the resulting order
        #   of machines is reversed.
        # @option options [Boolean] :single_target If true, then an
        #   exception will be raised if more than one target is found.
        def with_target_vms(names=nil, options=nil)

View on GitHub (pinned to 35f3160f4a)

Solutions

Re-run with `--help` to see the exact accepted syntax
Fix the typo or supply the missing option value
Confirm the option exists in your Vagrant version — flags changed across releases (check `vagrant <cmd> --help` output)

Example fix

# before
vagrant up --provder=virtualbox

# after
vagrant up --provider=virtualbox

Defensive patterns

Strategy: validation

Try / catch

begin
  command.parse_options(argv)
rescue Vagrant::Errors::CLIInvalidOptions => e
  warn e.extra_data[:help] # reprint full usage for the caller
end

Prevention

Spell out long options fully in scripts; avoid ambiguous abbreviations
Always provide values for options that take them (--provider virtualbox)
Pin the Vagrant version in CI so documented flags remain valid
Smoke-test scripted commands with --help after Vagrant upgrades

When it happens

Trigger: `vagrant snapshot save` missing its mandatory name argument (MissingArgument); `vagrant up --provder=virtualbox` with a typo (InvalidOption); an ambiguous abbreviated long option (AmbiguousOption) — any v2 command whose opt_parser rejects the given argv.

Common situations: Typo'd long flags; forgetting the value for options like --provider; scripts written against a different Vagrant release whose flag set changed; abbreviating long options that are no longer unique.

Related errors

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