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

The `vagrant snapshot` command is a subcommand dispatcher (save, restore, list, delete). When the first non-option token is missing or does not name a registered subcommand, the root command raises CLIInvalidUsage and prints the full snapshot help. This happens before any machine is touched.

Source

Thrown at plugins/commands/snapshot/command/root.rb:62

          @subcommands.register(:pop) do
            require_relative "pop"
            Pop
          end
        end

        def execute
          if @main_args.include?("-h") || @main_args.include?("--help")
            # Print the help for all the commands.
            @env.ui.info(help, prefix: false)
            return 0
          end

          # If we reached this far then we must have a subcommand. If not,
          # then we also just print the help and exit.
          command_class = @subcommands.get(@sub_command.to_sym) if @sub_command
          if !command_class || !@sub_command
            raise Vagrant::Errors::CLIInvalidUsage,
              help: help()
          end
          @logger.debug("Invoking command class: #{command_class} #{@sub_args.inspect}")

          # Initialize and execute the command class
          command_class.new(@sub_args, @env).execute
        end

        # Prints the help out for this command
        def help
          opts = OptionParser.new do |opts|
            opts.banner = "Usage: vagrant snapshot <subcommand> [<args>]"
            opts.separator ""
            opts.separator "Available subcommands:"

            # Add the available subcommands as separators in order to print them
            # out as well.
            keys = []

View on GitHub (pinned to 35f3160f4a)

Solutions

Run `vagrant snapshot -h` to list the valid subcommands for your version
Use the exact subcommand name, e.g. `vagrant snapshot delete snap1`
Upgrade Vagrant if documentation describes a subcommand your installed version lacks

Example fix

# before
vagrant snapshot del snap1

# after
vagrant snapshot delete snap1

Defensive patterns

Strategy: validation

Validate before calling

valid = %w[save restore list delete]
sub = ARGV[0]
abort "unknown subcommand #{sub}; valid: #{valid.join(', ')}" unless valid.include?(sub)
system('vagrant', 'snapshot', *ARGV)

Try / catch

begin
  VagrantPlugins::CommandSnapshot::Command.new(argv, env).execute
rescue Vagrant::Errors::CLIInvalidUsage => e
  warn e.extra_data[:help]
  exit 1
end

Prevention

Validate the subcommand against the installed version's help output before invoking
Pin the Vagrant version in CI so subcommand sets do not shift
Use `vagrant snapshot -h` as the source of truth when writing wrappers

When it happens

Trigger: `vagrant snapshot` with no subcommand; a misspelled subcommand like `vagrant snapshot del snap1` or `vagrant snapshot rm snap1`; a subcommand that exists in a newer Vagrant release than the one installed.

Common situations: Users coming from virsh/other tooling expecting `rm`/`remove`; scripts written against a different Vagrant version's subcommand set; muscle memory from `vagrant snapshot save` shortening to an invalid form.

Related errors

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