abiosoft/colima · error

invalid disk image: %w

Error message

invalid disk image: %w

What it means

While provisioning the VM image, Colima supports a user-supplied disk image via the DiskImage config. Before using it, the file is verified on the host with os.Stat; any stat failure (missing file, permission denied, dangling symlink, bad path) is wrapped as 'invalid disk image'. This is a host-side path check that happens before any digest validation.

Source

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

			"{mount_point}", mountPoint,
			"{name}", dir.Name,
			"{data_path}", dir.Path,
		).Replace("[ -d {mount_point} ] && mkdir -p {mount_point}/{name} {data_path} && mount --bind {mount_point}/{name} {data_path}")

		l.limaConf.Provision = append(l.limaConf.Provision, limaconfig.Provision{
			Mode:   "dependency",
			Script: script,
		})
	}
}

func (l *limaVM) downloadDiskImage(ctx context.Context, conf config.Config) error {
	log := l.Logger(ctx)

	// 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

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Verify the path exists and is readable: `ls -la /path/to/image` run as the same user that starts Colima.
2. Use an absolute path in the config/flag to avoid cwd-dependent resolution.
3. If the image is missing, download the correct image for your architecture and runtime, or omit diskImage to let Colima fetch/cache it automatically.
4. Check for trailing quotes/spaces in YAML values (e.g. `disk-image: "~/images/img.qcow2 "`).

Example fix

# before
colima start --disk-image ./ubuntu.qcow2   # file absent or mistyped

# after
ls -la /absolute/path/to/ubuntu.qcow2
colima start --disk-image /absolute/path/to/ubuntu.qcow2

// before colima start --disk-image
if fi, err := os.Stat(diskImagePath); err != nil || fi.IsDir() {
    log.Fatalf("disk image path invalid: %v", err)
}

When it happens

Trigger: Setting the diskImage config key (colima start --disk-image flag / config file) to a path that does not exist, is not readable by the current user, is a directory, or contains typos/relative-path mistakes. Also when the file sits on an unmounted external volume at start time.

Common situations: Air-gapped machines pointing at a pre-downloaded qcow2 image whose path changed; shell quoting issues with spaces in the path; images on removable media not yet mounted; wrong ~ expansion in YAML config.

Related errors

• error reading ssh config: %w
• error modifying %s: %w
• error preparing to copy VM: %w
• config missing for colima profile '%s': %w
• cannot copy config to new profile '%s': %w

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