Like many of you, I've installed my share of Virtualbox instances.

And there always come a dreaded moment: the one when you install the Guest Additions. It can fail for many reasons, sometimes with a misleading message.

Here are the reasons I've come to identify when installing a GNU/Linux guest.

  • Media locked
  • Execution denied
  • Missing kernel headers
  • Missing packages
  • Kernel headers mismatch
  • Out-of-date Virtualbox version

It all starts here in any case:

Device -> Insert Guest Additions CD Image

The diagnostics and suggested commands are for Debian.

Media locked

You get the error message:

Unable to insert the virtual optical disk
VERR_PDM_MEDIA_LOCKED

The CD is already mounted. Check on the desktop.

Permission denied

The Guest addition CD is mounted. You double-click VBoxLinuxAdditions.run in your file manager and nothing happens. If you open a terminal and run the script manually, you get:

root@debian:/media/cdrom # ./VBoxLinuxAdditions.run
bash: ./VBoxLinuxAdditions.run: Permission denied

Although permissions seems correct:

root@debian:/media/cdrom # ls -la VBoxLinuxAdditions.run
-r-xr-xr-x 1 root root 7146957 nov 21 15:58 VBoxLinuxAdditions.run

In /etc/fstab, change this:

/dev/sr0        /media/cdrom0   udf,iso9660 user,noauto     0       0

To this:

/dev/sr0        /media/cdrom0   udf,iso9660 user,exec     0       0

Remount and execute.

Note: you might also see briefly the same error after double clicking the program from the file manager, depending on the guest OS and desktop; you'll have to open a terminal to troubleshoot as described above.

Missing kernel headers

This one is obvious when kernel headers are actually missing:

The headers for the current running kernel were not found.
If the following module compilation fails then this could be the reason.

This is a warning message. If you see no error, try to restart the guest and see if it works. Otherwise, install the headers. But you might need extra packages too!

apt-get install build-essential linux-headers-`uname -r` dkms

Or maybe a more sustainable version would be:

apt-get install build-essential linux-headers-generic dkms

Missing packages

Your kernel headers are installed but you get the "headers for the current running kernel were not found" message. See above: you might be missing some packages.

Kernel headers mismatch

Your installation is probably not in the expected state. You have installed kernel headers, but they are more recent than the actual kernel.

root@debian:/ # uname -r
3.9-1-amd64

root@debian:/ # dpkg-query -l linux-headers
(...)
ii  linux-headers-3.16.0-4     amd64     Header files for Linux 3.16.0-4-amd64
ii  linux-headers-3.16.0-4     amd64     Common header files for Linux 3.16.0-4

Last time it happened to me, I simply upgraded the kernel:

apt-cache search linux-image
$ apt-get install linux-image-flavour

Out-of-date Virtualbox version

When none of the above seems to fix the problem, you might have an outdated version of Virtualbox. The sad thing is that you still get the misleading error message: "The headers for the current running kernel were not found", or the same error installing a VBox addition service.

Update Virtualbox to the latest version and try again.