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

Usage error from `vagrant snapshot delete [options] [vm-name] <name>`: after option parsing, the leftover positional arguments were empty (missing the snapshot name) or more than two. The command raises CLIInvalidUsage with its help text rather than guessing which snapshot to delete.

Source

Thrown at plugins/commands/snapshot/command/delete.rb:23

module VagrantPlugins
  module CommandSnapshot
    module Command
      class Delete < Vagrant.plugin("2", :command)
        def execute
          options = {}

          opts = OptionParser.new do |o|
            o.banner = "Usage: vagrant snapshot delete [options] [vm-name] <name>"
            o.separator ""
            o.separator "Delete a snapshot taken previously with snapshot save."
          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

          name = argv.pop
          with_target_vms(argv) do |vm|
            if !vm.provider.capability?(:snapshot_list)
              raise Vagrant::Errors::SnapshotNotSupported
            end

            snapshot_list = vm.provider.capability(:snapshot_list)

            if snapshot_list.include? name
              vm.action(:snapshot_delete, snapshot_name: name)
            else
              raise Vagrant::Errors::SnapshotNotFound,
                snapshot_name: name,
                machine: vm.name.to_s
            end

View on GitHub (pinned to 35f3160f4a)

Solutions

Use the exact form: `vagrant snapshot delete <name>` or `vagrant snapshot delete <vm-name> <name>`
Run `vagrant snapshot delete -h` to confirm the positional layout for your Vagrant version
Quote snapshot names containing spaces and remove stray arguments from the command line

Example fix

# before
vagrant snapshot delete
vagrant snapshot delete default snap1 extra

# after
vagrant snapshot delete snap1
vagrant snapshot delete default snap1

Defensive patterns

Strategy: validation

Validate before calling

positional = argv.reject { |a| a.start_with?('-') }
raise ArgumentError, 'usage: vagrant snapshot delete [vm-name] <name>' unless (1..2).cover?(positional.size)
system('vagrant', 'snapshot', 'delete', *positional)

Try / catch

begin
  command.execute
rescue Vagrant::Errors::CLIInvalidUsage => e
  warn e.extra_data[:help]
  exit 1
end

Prevention

Validate positional argument count before shelling out to snapshot subcommands
Quote snapshot names that contain spaces
Parse `vagrant snapshot delete -h` when writing wrappers so arity matches the installed version

When it happens

Trigger: `vagrant snapshot delete` with no positional argument; `vagrant snapshot delete snap1 extra` (three positionals after a vm-name is also included); an unrecognized flag left in argv so the name lands in the wrong position.

Common situations: Users expecting `vagrant snapshot delete` to prompt or delete the newest snapshot; scripts written with an extra flag after the name that optparse does not consume; snapshot names with unescaped spaces.

Related errors

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