Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Troubleshooting and Alternatives

Debugging and Common Vagrant Errors

Diagnose Vagrant problems with debug logs, the provider GUI and status commands, and fix the usual errors: SSH timeouts, port collisions, box and shared folder failures.

Sooner or later vagrant up fails. Vagrant's messages are usually informative, but they sit on top of a provider, a network, an operating system and your Vagrantfile, so the real cause can be several layers down. This lesson gives you a method: look at the state, get more information, then match the symptom to the usual causes.

Step 1: check the state

Start by asking what Vagrant and the provider believe is true.

TEXT
$ vagrant status            # this project's machines
$ vagrant global-status     # every machine Vagrant knows on this computer
$ vagrant global-status --prune   # forget machines that no longer exist
$ vagrant validate          # check the Vagrantfile for errors
$ vagrant version           # Vagrant version and latest available

vagrant validate catches Ruby syntax errors and unknown configuration keys before anything starts. Compare with the provider's own view: VBoxManage list runningvms, virsh list --all or the Hyper-V Manager. If vagrant status says "not created" but a VM with that name exists in the provider, you have an orphan; delete it in the provider.

Step 2: get more information

Vagrant has a built-in debug log. It is long but searchable.

TEXT
$ vagrant up --debug 2>&1 | tee vagrant-debug.log          # bash
PS> $env:VAGRANT_LOG = "debug"; vagrant up 2>&1 | Tee-Object vagrant-debug.log
$ VAGRANT_LOG=info vagrant up                                # less noisy

Search the log for ERROR and for the last few lines before it. For failures during boot, switch the GUI on to see the console:

Ruby
config.vm.provider "virtualbox" do |vb|
  vb.gui = true
end

A login prompt that appears but vagrant ssh never connects points to network or SSH setup; a kernel panic or a stuck boot screen points to the box or CPU settings. Also useful:

TEXT
$ vagrant ssh-config                 # the SSH settings Vagrant uses
$ ssh -F <(vagrant ssh-config) default   # try SSH yourself with them
$ vagrant provision --debug          # re-run provisioners with detail

Common errors and fixes

Timed out while waiting for the machine to boot

TEXT
Timed out while waiting for the machine to boot. This means that
Vagrant was unable to communicate with the guest machine within
the configured ("config.vm.boot_timeout" value) time period.

Possible causes, in order of likelihood:

  1. Virtualization disabled in the BIOS, or another hypervisor (Hyper-V, WSL 2 features) holding it. Enable VT-x/AMD-V and check for conflicts.
  2. Not enough memory or CPU for the guest; reduce vb.memory.
  3. A slow first boot. Raise the limit: config.vm.boot_timeout = 600.
  4. A network adapter problem; try vb.customize ["modifyvm", :id, "--nictype1", "virtio"] or the default 82540EM.
  5. A broken box: remove and re-add it.

Authentication failure / SSH issues

TEXT
default: Warning: Authentication failure. Retrying...

Common causes: a box that changed its SSH key, config.ssh.insert_key = false mismatching the box, or a corrupted .vagrant state. Fixes: vagrant destroy -f && vagrant up, or rm -rf .vagrant after destroying the VM in the provider. For a box that requires a password, set config.ssh.username and config.ssh.password.

Port collision

TEXT
Vagrant cannot forward the specified ports on this VM, since they would collide with some other application that is already listening on these ports.

Another program (or another machine) uses the host port. Either change host: or let Vagrant choose: auto_correct: true. Find the culprit with netstat -ano | findstr 8080 on Windows or lsof -i :8080 on Linux and macOS.

The box could not be found or downloaded

TEXT
The box 'team/java17' could not be found or could not be accessed in the remote catalog.

Check the spelling, the box_url, that you have network access, and for private boxes that you ran vagrant cloud auth login. A download that fails halfway leaves a partial file: vagrant box remove and add it again.

Shared folder mount errors

TEXT
Vagrant was unable to mount VirtualBox shared folders. The mount command exited with a failure...

The guest lacks matching Guest Additions. Install vagrant-vbguest, or switch the synced folder type to rsync or nfs. See the plugin lesson for vbguest.

A provisioner fails

TEXT
The SSH command responded with a non-zero exit status.

Vagrant prints the failing command and its output. Re-run it with vagrant provision, or enter the machine and run the script by hand to read the error. Add set -euxo pipefail at the top of shell scripts so the failing line is obvious and stops the run.

"Vagrantfile syntax error" or unknown configuration section

Run vagrant validate. An "unknown configuration section" nearly always means a missing plugin; see the plugin lesson.

VirtualBox says it cannot start the VM

Messages such as VERR_VMX_NO_VMX or "VT-x is not available" mean virtualization is off or taken by another hypervisor. Others, like a lingering lock, call for VBoxManage list runningvms and a clean VBoxManage controlvm <id> poweroff.

When all else fails

Work from least to most destructive:

  1. vagrant reload --provision
  2. vagrant halt then vagrant up
  3. vagrant destroy -f && vagrant up
  4. Delete the project's .vagrant folder after removing the VM in the provider.
  5. vagrant box remove and re-add the box.
  6. vagrant plugin expunge --reinstall.
  7. Update Vagrant and the provider together; a mismatch (for example a too-new VirtualBox) is a frequent cause after upgrades.

Because the Vagrantfile is the source of truth, rebuilding is cheap if your provisioning is complete. That is the real test of a good environment.

A stand-in: a symptom matcher

Matching an error to a likely cause is pattern matching on text. This Ruby program does exactly that with a small table, the same idea behind searching a debug log. It is a learning aid, not a Vagrant feature.

Ruby Diagnose log lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Common mistakes while debugging

  • Fixing symptoms in the VirtualBox GUI instead of in the Vagrantfile.
  • Skipping the log. --debug shows the exact command that failed.
  • Deleting .vagrant while the VM still exists, leaving an orphan in the provider.
  • Changing many things at once. Change one, rebuild, test.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command checks the Vagrantfile for errors without starting anything?

    vagrant validate reports syntax and configuration problems.
  2. 2. vagrant up hangs and then says it timed out waiting for the machine to boot. What is a sensible first check?

    The console shows whether the guest is booting, stuck or panicking, and virtualization or memory problems are the usual causes.
  3. 3. 'Unknown configuration section hostmanager' most likely means...

    A config section that Vagrant does not know comes from a plugin that is not installed.
  4. 4. How do you get a detailed log of a run?

    --debug or the VAGRANT_LOG environment variable prints a detailed trace.

Summary

  • Check state (status, global-status, validate), then raise the log level and use the provider GUI.
  • Learn the usual suspects: boot timeouts, SSH authentication, port collisions, box downloads, shared folders, missing plugins.
  • Escalate from reload to destroy to removing boxes and plugins.
  • Fix problems in the Vagrantfile, not by hand in the provider.

Next: Performance and Windows issues