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

cloud-init is not found. Please ensure that cloud-init is in

Error message

cloud-init is not found. Please ensure that cloud-init is installed and
available on path for guest '%{guest_name}'.

What it means

The cloud_init_wait middleware only waits on cloud-init when vm.cloud_init_configs is non-empty; before waiting it probes the guest with `command -v cloud-init`. If that probe fails, the box has no cloud-init binary and Vagrant raises CloudInitNotFound, because the requested cloud_init workflow can never run there.

Source

Thrown at lib/vagrant/action/builtin/cloud_init_wait.rb:41

              contents = sentinel_path.read.chomp
              if machine.id.to_s == contents
                @logger.info("Sentinel found for cloud-init, skipping")
                throw :complete
              end
              @logger.debug("Found stale sentinel file, removing... (#{machine.id} != #{contents})")
              sentinel_path.unlink
            end

            cloud_init_wait_cmd = "cloud-init status --wait"
            if !machine.config.vm.cloud_init_configs.empty?
              if machine.communicate.test("command -v cloud-init")
                env[:ui].output(I18n.t("vagrant.cloud_init_waiting"))
                result = machine.communicate.sudo(cloud_init_wait_cmd, error_check: false)
                if result != 0
                  raise Vagrant::Errors::CloudInitCommandFailed, cmd: cloud_init_wait_cmd, guest_name: machine.name
                end
              else
                raise Vagrant::Errors::CloudInitNotFound, guest_name: machine.name
              end
            end
            # Write sentinel path
            sentinel_path.write(machine.id.to_s)
          end

          @app.call(env)
        end
      end
    end
  end
end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Switch to a box that ships cloud-init preinstalled (official Ubuntu/Debian/cloud-images boxes, 'cloud' variants).
2. Or install cloud-init into the box once (`vagrant ssh -c 'sudo apt-get update && sudo apt-get install -y cloud-init'`), then `vagrant package` it and use the repackaged box.
3. If you cannot change the box, replace the cloud_init config with an equivalent shell provisioner.

Example fix

# before
Vagrant.configure("2") do |config|
  config.vm.box = "my-minimal-box"        # no cloud-init inside
  config.vm.cloud_init do |cloud_init|
    cloud_init.user_data = "#cloud-config\npackages: [htop]\n"
  end
end

# after: either use a cloud-init capable box, or provision via shell
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  # or: config.vm.provision "shell", inline: "apt-get update && apt-get install -y htop"
end

# Choose/probe a cloud-init capable box before relying on cloud_init configs
# after first bring-up of a candidate box:
vagrant ssh -c 'command -v cloud-init' >/dev/null 2>&1 \
  && echo "box supports cloud_init" \
  || echo "box lacks cloud-init: use a cloud image or shell provisioning"

When it happens

Trigger: `vagrant up` with any `config.vm.cloud_init` entry while the base box lacks cloud-init (lib/vagrant/action/builtin/cloud_init_wait.rb:37-42). Typical with hand-rolled minimal boxes, stripped cloud images, or Windows guests without cloud-init for Windows.

Common situations: Custom/Packer-built boxes without cloud-init installed; minimal distro images (Alpine, tiny Debian) where cloud-init was never added; assuming every 'linux box' ships cloud-init because Ubuntu cloud images do.

Related errors

• Vagrant cannot create an iso due to the host capability for
• cloud init command '%{cmd}' failed on guest '%{guest_name}'.
• The "metadata.json" file for the box '%{name}' was not found
• The metadata associated with the box '%{name}' appears corru
• The metadata associated with the box '%{name}' appears to be

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