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

cloud init command '%{cmd}' failed on guest '%{guest_name}'.

Error message

cloud init command '%{cmd}' failed on guest '%{guest_name}'.

What it means

During boot, the cloud_init_wait middleware runs `cloud-init status --wait` via sudo in the guest (error_check disabled). A non-zero exit code means cloud-init itself executed and reported failure, so Vagrant raises CloudInitCommandFailed with the command and guest name. The root cause is almost always in the user_data/meta_data you shipped, not in Vagrant.

Source

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

            @logger.info("Checking cloud-init sentinel file...")
            if sentinel_path.file?
              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. Inspect the guest logs: `vagrant ssh -c 'cloud-init status --long'` and `vagrant ssh -c 'sudo tail -n 100 /var/log/cloud-init.log /var/log/cloud-init-output.log'`.
2. Fix the user_data identified in the logs (usually a YAML/schema error), then `vagrant destroy && vagrant up` so the corrected NoCloud ISO is regenerated.
3. Validate the config before re-upping: `cloud-init schema --config-file user-data` on any machine with cloud-init installed.
4. If the failure is a transient network/package error, fix connectivity and re-run cloud-init in the guest (`sudo cloud-init clean --logs && sudo reboot`) or just recreate the VM.

Example fix

# before (invalid user_data: missing #cloud-config header)
config.vm.cloud_init do |cloud_init|
  cloud_init.user_data = "packages:\n  - htop\n"
end

# after
config.vm.cloud_init do |cloud_init|
  cloud_init.user_data = "#cloud-config\npackages:\n  - htop\n"
end

# Validate user_data before `vagrant up`
# (a) at minimum, parse the YAML
ruby -ryaml -e 'YAML.load_file("user-data") or raise "empty"' 2>/dev/null || echo "invalid YAML"
# (b) with cloud-init installed: schema check
grep -q '^#cloud-config' user-data && cloud-init schema --config-file user-data && echo OK

When it happens

Trigger: `vagrant up`/`vagrant reload` with vm.cloud_init_configs non-empty, cloud-init present in the guest, and `sudo cloud-init status --wait` exiting non-zero (lib/vagrant/action/builtin/cloud_init_wait.rb:34-39). Typical causes: user_data that is not valid #cloud-config YAML, failing runcmd/write_files modules, or package installation failures inside cloud-init.

Common situations: Malformed user_data (missing `#cloud-config` header, tabs, bad indentation); write_files with wrong permissions; apt/yum failures from network issues; conflicting cloud-init modules; slow mirrors causing module errors.

Related errors

• This Vagrant environment has specified that it requires the
• The box '%{name}' could not be found or could not be accesse
• There was an error while downloading the metadata for this b
• Multiple URLs for a box can't be specified when adding versi
• The box you're adding has a name different from the name you

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