I had a power outage the other night and it looks like one of my VirtualBox virtual images got a little corrupt and it’s UUID changed. This isn’t espcially a problem, but VirtualBox identifies images by the UUID and therefore refused to start the VM this is attached to throwing the error:

UUID {b6e58671-d821-4dba-b723-f12defc2650a} of the medium ‘/home/admin1/vimages/zen.vdi’ does not match the value {c14b3de3-78c8-40a1-8106-badd0e0fb9c2} stored in the media registry (‘/home/admin1/.VirtualBox/VirtualBox.xml’)

I hacked the VirtualBox.xml file to reflect the new UUID but it still gave me the same error. I guess VirtualBox must cache it somewhere.

I ran:

VBoxManage internalcommands setuuid “/home/admin1/vimages/zen.vdi”

Which said it ran successfully, but then gave me the same error when I tried to start the VM. Weird. Cloning the VDI also fails with the same message, so I can’t generate a new virtual image from this one either.

I have in fact had this issue when using the Mac version of VirtualBox, and I removed the image from the HD listing and re-added it, forcing VirtualBox to accept the new UUID of the image. Unfortunately, I couldn’t find in the manual how to perform this step on the command line. Simly detaching and reattaching the media does not force VirtualBox to change the media registry.

Eventually after molesting Google to broaden my search way beyond my error message (effectively looking at everyone who had UUID errors in VirtualBox!) I came accross the unregisterimage command. Intuitively I discovered there is an identical reverse command called registerimage. These commands control the media library from the command line. They appear to be compeltely undocumented in the VirtualBox Manual. It’s quite stupid really, they should be in the same section where the GUI describes how to do this.
A quick detachment of the drive from my VM:

VBoxManage storageattach zen –storagectl “IDE Controller” –port 0 –device 0 –medium none

Followed by resetting the image registration:

VBoxManage unregister “/home/admin1/vimages/ubuntu.vdi”
VBoxManage register “/home/admin1/vimages/ubuntu.vdi”

And re-attaching the drive:

VBoxManage storageattach zen –storagectl “IDE Controller” –port 0 –device 0 –type hdd –medium “/home/admin1/vimages/ubuntu.vdi”

And all was good!

UPDATE 11th OCT 2011: This won’t work in Virtualbox 4.x as they changed the commands. I cannot see any VBoxManage command to take the place of the register / unregister commands and I have resorted to using PHPVirtualBox to do this as it has a media manager built in but still allows me to run the server headless.