hashicorp/vagrant · error · VagrantPlugins::DockerProvisioner::DockerError

Docker installation failed.

Error message

Docker installation failed.

What it means

Raised by the Docker installer's ensure_installed: if the guest lacks the `docker_installed` capability it only warns and returns false (provisioning continues without docker management); but when the capability exists, installation runs (`docker_install`), and a follow-up `docker_installed` check still reporting absence triggers install_failed. The installer output streamed before the raise contains the actual package-manager error from inside the guest.

Source

Thrown at plugins/provisioners/docker/installer.rb:26

    class Installer < VagrantPlugins::ContainerProvisioner::Installer
      # This handles verifying the Docker installation, installing it if it was
      # requested, and so on. This method will raise exceptions if things are
      # wrong.
      # @return [Boolean] - false if docker cannot be detected on machine, else
      #                     true if docker installs correctly or is installed
      def ensure_installed
        if !@machine.guest.capability?(:docker_installed)
          @machine.ui.warn(I18n.t("vagrant.docker_cant_detect"))
          return false
        end

        if !@machine.guest.capability(:docker_installed)
          @machine.ui.detail(I18n.t("vagrant.docker_installing"))
          @machine.guest.capability(:docker_install)
        end

        if !@machine.guest.capability(:docker_installed)
          raise DockerError, :install_failed
        end

        if @machine.guest.capability?(:docker_configure_vagrant_user)
          @machine.guest.capability(:docker_configure_vagrant_user)
        end

        true
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Read the installer output above the raise - it shows the package manager failure
2. SSH in and retry manually to see the error: `vagrant ssh -c 'sudo apt-get install docker-ce'` (or dnf/yum)
3. Fix guest network/proxy/DNS and run `vagrant provision` again
4. Preinstall Docker in a custom box; the capability check then passes and install is skipped

Example fix

# Vagrantfile - before
config.vm.provision "docker"

# Vagrantfile - after (pre-provision the repo so the installer works)
config.vm.provision "shell", inline: <<-SHELL
  apt-get update && apt-get install -y ca-certificates curl gnupg
SHELL
config.vm.provision "docker"

# Pre-flight from host: can the guest reach the docker repo?
system("vagrant ssh -c 'curl -sI https://download.docker.com >/dev/null && echo OK'") or
  abort "Guest cannot reach download.docker.com - docker install will fail"

begin
  env.cli(%w[provision])
rescue VagrantPlugins::DockerProvisioner::DockerError => e
  abort "Docker install failed: run `vagrant ssh -c 'sudo journalctl -u docker'` and fix guest network" if e.message == "Docker installation failed."
  raise
end

When it happens

Trigger: Docker provisioner on a guest where `docker_install` ran (apt/yum/dnf script) but the post-install check cannot find a working docker binary - failed downloads, unsupported distro version, broken package repos, or docker installed to a non-standard location the capability does not probe.

Common situations: Corporate proxy blocking download.docker.com in the guest; very new/old distro release without a repo entry; apt lock or disk-full during install; minimal images where the install script silently failed.

Related errors

• Multiple URLs for a box can't be specified when adding versi
• Vagrant could not detect Chef on the guest! Even after Vagra
• The Docker post-install provisioner cannot also take a Docke
• Docker is not running on the guest VM.
• Podman installation failed.

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