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 restore [options] [vm-name] <name>`: after parsing, zero positional arguments (no snapshot name) or more than two were supplied. Restore needs exactly one snapshot name, optionally preceded by a vm-name, so Vagrant prints help via CLIInvalidUsage instead of restoring an ambiguous target.

Source

Thrown at plugins/commands/snapshot/command/restore.rb:35

          options[:provision_ignore_sentinel] = false
          options[:snapshot_start] = true

          opts = OptionParser.new do |o|
            o.banner = "Usage: vagrant snapshot restore [options] [vm-name] <name>"
            o.separator ""
            build_start_options(o, options)
            o.separator "Restore a snapshot taken previously with snapshot save."

            o.on("--no-start", "Don't start the snapshot after the restore") do
              options[:snapshot_start] = false
            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

          # Validate the provisioners
          validate_provisioner_flags!(options, argv)

          name = argv.pop
          options[:snapshot_name] = name

          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_restore, options)

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Use the exact form: `vagrant snapshot restore <name>` or `vagrant snapshot restore <vm-name> <name>`
  2. Put options (`--no-start`, provisioner flags) before the snapshot name and quote names with spaces
  3. Run `vagrant snapshot restore -h` to re-check the argument layout

Example fix

# before
vagrant snapshot restore --no-start

# after
vagrant snapshot restore --no-start clean-state
Defensive patterns

Strategy: validation

Validate before calling

positional = argv.reject { |a| a.start_with?('-') }
raise ArgumentError, 'usage: vagrant snapshot restore [vm-name] <name>' unless (1..2).cover?(positional.size)
system('vagrant', 'snapshot', 'restore', *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 restore` with no snapshot name; three or more positionals after parsing; flags such as `--no-start` placed so that optparse leaves extra tokens in argv.

Common situations: Users adding `--provision-with` or `--no-start` in the wrong position; scripts written against `vagrant snapshot restore <vm> <name> <extra>` from older tooling; names with spaces unquoted.

Related errors

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