Virtkick Docs

Documentation and information to Virtkick your business

Custom ISO Troubleshooting Steps

So your custom ISO isn't working - bummer! We're here to help you get that fixed with some troubleshooting steps you can take to correct problematic ISOs.

1. Can you download your ISO from your hypervisor?

The most common problem with custom ISOs is a faulty download mirror. Install aria2c on your hypervisor and then try downloading your ISO via the mirror URL you provided to your panel. The command would look similar to this:


Aria should tell you what is wrong with the path - for example the ISO may no longer exist. If that is the case you may need to fix your web server or find a different mirror for this ISO.

2. Is the file type correct?

Sometimes the image may download but still not work for other reasons. One of these reasons is the file type is wrong. Navigate to /home/virtkick/iso/.work and find your file. After you have located it try running the file command like so:

file yourisofile.iso

If all is well, your output should look something like this:

archlinux-2015.12.01-dual.iso: DOS/MBR boot sector ISO 9660 CD-ROM filesystem data (DOS/MBR boot sector) 'ARCH_201512' (bootable); partition 2 : ID=0xef, start-CHS (0x3ff,254,63), end-CHS (0x3ff,254,63), startsector 252, 63488 sectors

If it doesn't, your ISO may be improperly formatted. You can either correct the ISO if you know how, or look for an alternative source for the ISO.

3. Did you provide the correct checksum?

We highly advise that you provide a checksum when you add a new image. This makes sure the image isn't corrupted during transfer. Here's how to obtain a checksum of your image:

sha512sum yourisofile.iso

The output will be like this:

02bfe9b484664d324c09978665b060b0a8cdd1eb06e348fdc644b409589f654a2f46f71e66e8555ab459ebbd885ae90e2db61f486e3eeed21a9dd14fa17f3d24  yourisofile.iso

And the left part of the output is the checksum you should submit in Virtkick:


If you don't provide a checksum, Virtkick will download the file and assume it's authentic, not corrupted, and will memorize the checksum for future downloads. You shouldn't rely on it, though.

4. Is the image compressed?

Finally, check to see if your ISO is compressed. We currently support raw ISOs only, so if your file ends in .zip or .gz, you need to provide an uncompressed ISO. Your ISOs should end in .iso if they are to work properly.

Need more help?

If you need additional help please feel free to reach out to us - we are always happy to help!

Back to the list ยป

Joe Pettit
Developer @ Virtkick
comments powered by Disqus