abiosoft/colima · error

disk image must be downloaded from '%s', hash failure: %w

Error message

disk image must be downloaded from '%s', hash failure: %w

What it means

A user-supplied disk image must be byte-identical to Colima's official image: downloader.SHA (SHA-512) validates the file against the digest from limautil.Image. A mismatch means the file is not the expected artifact (different version, corrupted download, modified image). Unless ForceDiskImage is set, provisioning fails rather than booting an unverified image.

Source

Thrown at environment/vm/lima/disk.go:165

	// use a user specified disk image
	if conf.DiskImage != "" {
		if _, err := os.Stat(conf.DiskImage); err != nil {
			return fmt.Errorf("invalid disk image: %w", err)
		}

		image, err := limautil.Image(l.limaConf.Arch, conf.Runtime)
		if err != nil {
			return fmt.Errorf("error getting disk image details: %w", err)
		}

		sha := downloader.SHA{Size: 512, Digest: image.Digest}
		if err := sha.ValidateFile(l.host, conf.DiskImage); err != nil {
			if conf.ForceDiskImage != nil && *conf.ForceDiskImage {
				log.Warnln("unable to validate disk image, but continuing as requested...")
				image.Digest = "" // clear so lima does not re-validate
			} else {
				return fmt.Errorf("disk image must be downloaded from '%s', hash failure: %w", image.Location, err)
			}
		}

		image.Location = conf.DiskImage
		l.limaConf.Images = []limaconfig.File{image}
		return nil
	}

	// use a previously cached image
	if image, ok := limautil.ImageCached(l.limaConf.Arch, conf.Runtime, conf.DiskImageMirror); ok {
		l.limaConf.Images = []limaconfig.File{image}
		return nil
	}

	// download image
	log.Infoln("downloading disk image ...")
	image, err := limautil.DownloadImage(l.limaConf.Arch, conf.Runtime, conf.DiskImageMirror)
	if err != nil {

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Download the exact official image from the location named in the error and retry with that file.
2. If the custom image is intentional, bypass verification with the force flag (e.g. `colima start --disk-image /path --force-disk-image`) and accept the warning; the digest is cleared so Lima will not re-validate.
3. Re-verify the file yourself (`shasum -a 512 image`) against the expected digest to detect corruption, then re-download if it differs.
4. Upgrade/downgrade Colima so its embedded digest matches the image version you are supplying.

Example fix

# before
colima start --disk-image ./my-customized.qcow2   # digest mismatch -> error

# after
colima start --disk-image ./my-customized.qcow2 --force-disk-image   # warns and continues

// pre-verify the SHA-512 before handing the file to colima
// expected digest is published with the release artifact
if !sha512Matches(diskImagePath, expectedDigest) {
    if !forceDiskImage { log.Fatal("digest mismatch; re-download or pass --force-disk-image") }
}

When it happens

Trigger: Passing --disk-image with a locally built, trimmed, re-compressed, or partially downloaded qcow2; supplying an image for a different Colima version than the embedded digest; truncated transfer. The error is skipped only when conf.ForceDiskImage is true (which logs a warning and clears the digest).

Common situations: Offline/air-gapped installs with hand-copied images; mirrors that re-encode artifacts; resumable-download corruption; teams pinning custom hardened images.

Related errors

• invalid disk image: %w
• error getting disk image details: %w
• error getting qcow image: %w
• error retrieving current runtime: empty value
• runtime cannot be updated, %s is not running

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/45305303dce9579c. Report an issue: GitHub.