hashicorp/vagrant · error · VagrantPlugins::Salt::Errors::SaltError

vagrant.provisioners.salt.bootstrap_failed

Error message

vagrant.provisioners.salt.bootstrap_failed

What it means

SaltError with key :bootstrap_failed is raised at provisioner.rb:367 after the bootstrap script (bundled bootstrap_salt.sh / .ps1, or config.bootstrap_script) ran via communicate.sudo and returned falsy — i.e. the script exited non-zero. SaltError namespaces translations under vagrant.provisioners.salt, so the symbol resolves to the vagrant.provisioners.salt.bootstrap_failed locale key. It means Salt itself failed to install/configure inside the guest, not that Vagrant misbehaved.

Source

Thrown at plugins/provisioners/salt/provisioner.rb:367

              if @config.verbose
                @machine.env.ui.info(data.rstrip)
              end
            end
          else
            bootstrap = @machine.communicate.sudo("%s %s" % [bootstrap_destination, options]) do |type, data|
              if data[0] == "\n"
                # Remove any leading newline but not whitespace. If we wanted to
                # remove newlines and whitespace we would have used data.lstrip
                data = data[1..-1]
              end
              if @config.verbose
                @machine.env.ui.info(data.rstrip)
              end
            end
          end

          if !bootstrap
            raise Salt::Errors::SaltError, :bootstrap_failed
          end

          if configure and !install
            @machine.env.ui.info "Salt successfully configured!"
          elsif configure and install
            @machine.env.ui.info "Salt successfully configured and installed!"
          elsif !configure and install
            @machine.env.ui.info "Salt successfully installed!"
          end
        else
          @machine.env.ui.info "Salt did not need installing or configuring."
        end
      end

      def call_overstate
        if @config.run_overstate
          # If verbose is on, do not duplicate a failed command's output in the error message.
          ssh_opts = {}

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Re-run with --debug (and config.verbose = true) — the bootstrap output streamed just above the raise contains the real failing command (apt/yum/pip/curl)
2. Verify the guest has network access and working package repos before provisioning
3. If config.version is set, confirm that exact Salt version exists for the bootstrap script and guest platform
4. Point bootstrap_script at a known-good script, or omit it to use the bundled one
5. For WinRM guests, run the PowerShell bootstrap manually in the guest to expose the failing step

Example fix

# before
config.vm.provision :salt do |s|
  s.version = "v3000.99-does-not-exist"  # bootstrap exits non-zero -> bootstrap_failed
end

# after
config.vm.provision :salt do |s|
  s.version = "3006"
  s.verbose = true  # stream bootstrap output so failures are diagnosable
end

# Vagrantfile: smoke-test guest network before salt bootstrap runs
config.vm.provision "shell",
  inline: "curl -fsSI https://repo.saltproject.io >/dev/null || (echo 'no network for salt bootstrap'; exit 1)"

begin
  env.cli("provision")
rescue VagrantPlugins::Salt::Errors::SaltError => e
  # bootstrap_failed: inspect the streamed sudo output above this point
  abort "Salt bootstrap failed inside the guest - re-run with --debug"
end

When it happens

Trigger: run_bootstrap_script uploads the script (get_bootstrap: custom bootstrap_script or BootstrapDownloader's platform default), executes it with sudo (powershell.exe -NonInteractive ... -file for WinRM), and raises when communicate.sudo reports failure: unresolvable config.version pin, no network/package mirrors in the guest, unsupported distro in the script, or a custom bootstrap_script exiting non-zero.

Common situations: Pinning salt version to a tag the bootstrap script cannot resolve; guests without internet or with broken apt/yum repos; custom bootstrap scripts with bugs; Windows bootstraps failing on Python pre-reqs; slow mirrors timing out.

Related errors

• The requested Ansible version (%{required_version}) was not
• Ansible failed to complete successfully. Any error output sh
• The provisioner '%{name}' doesn't support provisioning on Wi
• The explicit capability host specified of '%{value}' could n
• The capability host could not be detected. This is an intern

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