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

A v1-API plugin command received a command-line option its OptionParser does not recognize; the rescue in parse_options (lib/vagrant/plugin/v1/command.rb:56) converts OptionParser::InvalidOption into CLIInvalidOptions and embeds the command's help text as %{help}. It is purely a usage error in the arguments passed to that subcommand. V1 is the legacy plugin API, so this error comes from old third-party plugin commands.

Source

Thrown at lib/vagrant/plugin/v1/command.rb:56

        # was printed and parsing failed.
        def parse_options(opts=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 ||= 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
          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 [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)
          # Using VMs requires a Vagrant environment to be properly setup
          raise Errors::NoEnvironmentError if !@env.root_path

          # Setup the options hash
          options ||= {}

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Re-run with `-h`/`--help` to list the options the command actually accepts
2. Fix the misspelled or unsupported flag in your command line or script
3. Update the plugin — the option may exist in a newer release
4. If you maintain the plugin, declare the option in the command's opt_parser block

begin
  command_class.parse(argv)
rescue Vagrant::Errors::CLIInvalidOptions => e
  # e.extra_data[:help] holds the command's full help text
  warn e.message
end

When it happens

Trigger: Running `vagrant <old-plugin-command> --unknown-flag` where the flag is not declared in the command's opt_parser OptionParser: a typo like `--provder`, an option removed in the installed plugin version, or an option that only exists in a newer release than the one installed.

Common situations: Typo'd flags in manual runs or scripts; commands copy-pasted from docs written for a different plugin version; shell aliases that append stale flags.

Related errors

• An invalid option was specified. The help for this command i
• A Vagrant environment or target machine is required to run t
• No virtual machines matched the regular expression given.
• A VM by the name of %{name} was not found.
• This command requires a specific VM name to target in a mult

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