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 save [options] [vm-name] <name>`: after option parsing there were no positional arguments left (missing the new snapshot's name) or more than two. The save command requires a name for the snapshot it creates, so Vagrant raises CLIInvalidUsage with its help text.

Source

Thrown at plugins/commands/snapshot/command/save.rb:36

            o.separator "can be restored via `vagrant snapshot restore` at any point in the"
            o.separator "future to get back to this exact machine state."
            o.separator ""
            o.separator "If no vm-name is given, Vagrant will take a snapshot of"
            o.separator "the entire environment with the same snapshot name."
            o.separator ""
            o.separator "Snapshots are useful for experimenting in a machine and being able"
            o.separator "to rollback quickly."

            o.on("-f", "--force", "Replace snapshot without confirmation") do |f|
              options[:force] = f
            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

          name = argv.pop

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

            # In this case, no vm name was given, and we are iterating over the
            # entire environment. If a vm hasn't been created yet, we can't list
            # its snapshots
            if vm.id.nil?
              @env.ui.warn(I18n.t("vagrant.commands.snapshot.save.vm_not_created",
                                  name: vm.name))
              next
            end

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Use the exact form: `vagrant snapshot save <name>` or `vagrant snapshot save <vm-name> <name>`
  2. Place `-f/--force` before the name and quote names with spaces
  3. Run `vagrant snapshot save -h` to confirm the layout

Example fix

# before
vagrant snapshot save -f

# after
vagrant snapshot save -f pre-experiment
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: `vagrant snapshot save` with no name; three or more positionals (e.g. `vagrant snapshot save default snap1 extra`); the `-f/--force` flag placed where it leaves stray tokens in argv.

Common situations: Users expecting an auto-generated snapshot name; scripts passing extra context words after the name; unquoted names containing spaces.

Related errors

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