Vagrant Tricks and Troubleshooting

10 Oct

Vagrant is awesome and most of the time things just work, but like any piece of software, occasionally things go wrong or don’t quite function as planned. I’ve gathered all the issues I’ve run into here and included things you can do to solve them. Hopefully they can help you to get where you’re going quickly. If you’re new to Vagrant, check out my tutorial here:

Sometimes it may become necessary to boot a machine with monitor attached for debugging. In these cases you’ll usually see a message like the following:

SSH connection was refused! This usually happens if the VM failed to
boot properly. Some steps to try to fix this: First, try reloading your
VM with `vagrant reload`, since a simple restart sometimes fixes things.
If that doesn't work, destroy your VM and recreate it with a `vagrant destroy`
followed by a `vagrant up`. If that doesn't work, contact a Vagrant
maintainer (support channels listed on the website) for more assistance.

You can have a look at what is going on by adding the following to your Vagrantfile:

config.vm.boot_mode = :gui

You should now be able to log in via the console as user vagrant with password vagrant. Once in, you should have the ability to become root using sudo to have a look at logs or make changes to the system.

[vagrant@vm-localhost ~]$ sudo su -
[root@vm-localhost ~]#

Occasionally you’ll try and boot a VM and Vagrant will get tired of waiting to connect via SSH before the machine is fully booted. You can increase the number of attempts as well as the maximum length of time vagrant will wait by massaging the following variables in the Vagrantfile

web_config.ssh.timeout = 300
web_config.ssh.max_tries = 300

By default, a Vagrant VM gets 384 Megabytes of RAM. Depending on what you’re actually running in the virtual machine, this might not be enough. You can adjust the RAM allocated to a VM in the Vagrantfile as well.

config.vm.customize do |vm|
 vm.memory_size = 512

Occasionally, you might boot up a VM and see a message such as the following:

[default] The guest additions on this VM do not match the install version of
VirtualBox! This may cause things such as forwarded ports, shared
folders, and more to not work properly. If any of those things fail on
this machine, please update the guest additions and repackage the

Guest Additions Version: 4.0.4
VirtualBox Version: 4.1.4

This is letting you know that the Virtual Box tools installed in the VM don’t match the Virtual Box version you are running on your system. We can fix this issue without doing a complete reinstall of our Base Box from scratch. Inside the VM you’ll need to have the appropriate version of the kernel headers package for your platform installed. In addition, you’ll need to ensure you have GCC

On Debian:

apt-get install linux-headers-$(uname -r) gcc

The RHEL or Centos equivalent:

yum install kernel-headers-$(uname -r) gcc

You need to download the guest additions from the Virtual Box website that match the version of Virtual Box you have installed. I prefer to do this outside the VM in the same directory as my Vagrantfile. This allows me to reuse the downloaded iso from in other VMs I have defined rather than download it over and over. To download version 4.1.4:

$ curl -L -O

From inside the VM, we’ll need to mount the ISO file we downloaded. The trick to making this happen is to mount it as a loop device.

[root@vm-localhost ~]# mount -o loop /vagrant/VBoxGuestAdditions_4.1.4.iso /mnt

Next we must move to the mounted ISO file and run the installer. Like me, you might get an error about the Window System drivers. This is just an artifact of my VM not having X11 installed.

[root@vm-localhost ~]# cd /mnt [root@vm-localhost mnt]# ./ Verifying archive integrity... All good. Uncompressing VirtualBox 4.1.4 Guest Additions for Linux......... VirtualBox Guest Additions installer Removing installed version 4.0.4 of VirtualBox Guest Additions... Removing existing VirtualBox DKMS kernel modules [ OK ] Removing existing VirtualBox non-DKMS kernel modules [ OK ] Building the VirtualBox Guest Additions kernel modules Not building the VirtualBox advanced graphics driver as this Linux version is too old to use it. Building the main Guest Additions module [ OK ] Building the shared folder support module [ OK ] Doing non-kernel setup of the Guest Additions [ OK ] You should restart your guest to make sure the new modules are actually used Installing the Window System drivers [FAILED] (Could not find the X.Org or XFree86 Window System.) [root@vm-localhost mnt]# cd ~ [root@vm-localhost ~]# umount /mnt 

At this point, you can call vagrant reload to reboot the running VM and with a bit of patience, you should see that the message about mismatched versions has disappeared. Great! We’ve fixed our VM, but wait, our base box is still broken. We don’t want to do this every time we make a new image from it. Luckily vagrant provides us with a handy tool for converting a VM to a base box.

$ vagrant halt
[default] Attempting graceful shutdown of linux...
[default] Forcing shutdown of VM...
$ vagrant package
[default] Clearing any previously set forwarded ports...
[default] Cleaning previously set shared folders...
[default] Creating temporary directory for export...
[default] Exporting VM...
[default] Compressing package to: /Users/zsprackett/test/

We can now either import it as a new base box and update our Vagrantfiles to use it, or we can remove the old one and replace it with the new one.

$ vagrant box remove
[vagrant] Deleting box ''...
$ vagrant box add
[vagrant] Downloading with Vagrant::Downloaders::File...
[vagrant] Copying box to temporary location...
[vagrant] Extracting box...
[vagrant] Verifying box...
[vagrant] Cleaning up downloaded box...

5 Responses to “Vagrant Tricks and Troubleshooting”

  1. JulienD December 20, 2011 at 11:59 am #

    Good collections of posts !

    Vagrant associated with a provisioning tools seems to be a good way to work easier on projects and to win lots of hours of server configurations.

    I would also add to this list of tips :
    > vagrant provision

    The command to do the provisioning again, usefull when you change your scripts or when you have an error during the installation.

    Thanks for sharing !

  2. Jakub Holý March 24, 2012 at 7:10 am #

    Useful, thanks.

    Notice that the VBoxGuestAdditions.iso appropriate for your installed Virtual Box version is available in VB’s installation folder, for Mac that would be /Applications/ – see

  3. it virtualization December 15, 2012 at 11:20 am #

    great article!
    thanks for the help, I’m new to Vagrant, I think I need to watch the tutorial first.

  4. Wim Mostmans (@Sitebase) March 5, 2013 at 4:44 am #

    Thanks for the info about how to update the VB Guest Additions, that was just what I was looking for.


  1. After Vagrant Crash How To Recover Database | Margots Kapacs Blog - February 23, 2013

    […] Vagrant Tricks And Troubleshooting […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.

Join 75 other followers

%d bloggers like this: