hashicorp/vagrant · error · Vagrant::Errors::SSHInsertKeyUnsupported

Vagrant is configured to generate a random keypair and inser

Error message

Vagrant is configured to generate a random keypair and insert it
onto the guest machine, but it appears Vagrant doesn't know how to do
this with your guest OS. Please disable key insertion by setting
`config.ssh.insert_key = false` in the Vagrantfile.

After doing so, run `vagrant reload` for the setting to take effect.

What it means

On first connect Vagrant replaces the insecure default key with a generated keypair. If the guest's capability chain cannot do either half of that (insert_public_key / remove_public_key), SSHInsertKeyUnsupported is raised instead of silently leaving the insecure key in place. The message tells you to disable key insertion with `config.ssh.insert_key = false` and reload.

Source

Thrown at plugins/communicators/ssh/communicator.rb:191

        end

        # If we used a password, then insert the insecure key
        ssh_info = @machine.ssh_info
        return if ssh_info.nil?
        insert   = ssh_info[:password] && ssh_info[:private_key_path].empty?
        ssh_info[:private_key_path].each do |pk|
          if insecure_key?(pk)
            insert = true
            @machine.ui.detail("\n"+I18n.t("vagrant.inserting_insecure_detected"))
            break
          end
        end

        if insert
          # If we don't have the power to insert/remove keys, then its an error
          cap = @machine.guest.capability?(:insert_public_key) &&
            @machine.guest.capability?(:remove_public_key)
          raise Vagrant::Errors::SSHInsertKeyUnsupported if !cap

          key_type = machine_config_ssh.key_type

          begin
            # If the key type is set to `:auto` check for supported type. Otherwise
            # ensure that the key type is supported by the guest
            if key_type == :auto
              key_type = catch(:key_type) do
                begin
                  Vagrant::Util::Keypair::PREFER_KEY_TYPES.each do |type_name, type|
                    throw :key_type, type if supports_key_type?(type_name)
                  end
                  nil
                rescue => err
                  @logger.warn("Failed to check key types server supports: #{err}")
                  nil
                end
              end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Set `config.ssh.insert_key = false` in the Vagrantfile and run `vagrant reload` (exactly as the error instructs)
2. Fix guest detection so real capabilities load: use a standard box whose OS Vagrant recognizes
3. Replace the insecure key manually (ssh-copy-id or provider console) if rotation is required without the capability

Example fix

# before
Vagrant.configure('2') do |config|
  config.vm.box = 'custom-appliance'
end
# vagrant up  ->  SSHInsertKeyUnsupported

# after
Vagrant.configure('2') do |config|
  config.vm.box = 'custom-appliance'
  config.ssh.insert_key = false
end
# then: vagrant reload

unless machine.guest.capability?(:insert_public_key) && machine.guest.capability?(:remove_public_key)
  warn 'guest cannot rotate SSH keys; set config.ssh.insert_key = false in the Vagrantfile'
end

begin
  env.cli('up')
rescue Vagrant::Errors::SSHInsertKeyUnsupported
  # append `config.ssh.insert_key = false` to the Vagrantfile, then run `vagrant reload`
end

When it happens

Trigger: Booting a box whose guest detection falls back to a generic/unknown guest without insert_public_key or remove_public_key capabilities; stripped-down appliances or containers missing the tools those capabilities require; misdetected guest OS selecting the wrong guest plugin.

Common situations: Custom minimal base boxes; appliance-like guests; boxes built years ago running on newer Vagrant versions where key-insertion capability requirements tightened.

Related errors

• The private key you are attempting to generate is not suppor
• The box you're attempting to add has no available version th
• The provider for this Vagrant-managed machine is reporting t
• The provider for this Vagrant-managed machine is reporting t
• The provider for this Vagrant-managed machine is reporting t

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