lima-vm/lima · error

base disk (%#q) child must not have a different filename (%#

Error message

base disk (%#q) child must not have a different filename (%#q)

What it means

AcceptableAsBaseDisk inspects `qemu-img info` output (Info.Children, populated since QEMU 8.0) to ensure a base disk image contains no suspicious external references. A qcow2 image normally has no children; if it reports exactly one child, that child must reference the image's own filename (e.g. a self-referencing format structure). When the child's filename differs from the base disk's filename, it means the image embeds a reference to a different file — likely a backing file or extent — which is treated as an untrusted external file reference that could exfiltrate host files into the guest.

Source

Thrown at pkg/qemuimgutil/qemuimgutil.go:286

// AcceptableAsBaseDisk checks if a disk image is acceptable as a base disk.
func AcceptableAsBaseDisk(info *Info) error {
	switch info.Format {
	case "qcow2", "raw":
		// NOP
	default:
		logrus.WithField("filename", info.Filename).
			Warnf("Unsupported image format %#q. The image may not boot, or may have an extra privilege to access the host filesystem. Use with caution.", info.Format)
	}
	if err := rejectExternalFileReferences(info); err != nil {
		return err
	}
	// info.Children is set since QEMU 8.0
	switch len(info.Children) {
	case 0:
	// NOP
	case 1:
		if info.Filename != info.Children[0].Info.Filename {
			return fmt.Errorf("base disk (%#q) child must not have a different filename (%#q)", info.Filename, info.Children[0].Info.Filename)
		}
		if len(info.Children[0].Info.Children) > 0 {
			return fmt.Errorf("base disk (%#q) child must not have children of its own", info.Filename)
		}
	default:
		return fmt.Errorf("base disk (%#q) must not have multiple children: %+v", info.Filename, info.Children)
	}
	return nil
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Flatten the image to remove the backing chain: run `qemu-img convert -O qcow2 image.qcow2 flattened.qcow2` and use the flattened file as the base disk.
2. Re-download or rebuild the base image from an official Lima template source so it is a self-contained qcow2/raw file.
3. Commit the backing chain into one file: `qemu-img commit` on the child, then verify with `qemu-img info` that no external references remain.

Example fix

// before: base disk is a qcow2 with a backing file
//   qemu-img create -f qcow2 -b base.qcow2 -F qcow2 overlay.qcow2; use overlay.qcow2 as base disk
// after
//   qemu-img convert -O qcow2 overlay.qcow2 selfcontained.qcow2
//   limactl start --disk selfcontained.qcow2

// Before using an image as a base disk, inspect it yourself:
// qemu-img info --output=json disk.qcow2
// jq -e '."snapshots" == null and (."backing-filename" | not)' disk-info.json 
// Ensure no backing file and that any child entry has the same filename as the image.
func hasSelfReferencingChildOnly(infoJSON []byte) bool { /* parse qemu-img info; len(children)<=1 && children[0].filename == top filename */ return true }

func acceptableBaseDiskFilename(info Info) bool {
	return len(info.Children) == 0 ||
		(len(info.Children) == 1 && info.Children[0].Info.Filename == info.Filename)
}

When it happens

Trigger: Calling AcceptableAsBaseDisk (via EnsureDisk) on a qcow2/raw image whose qemu-img info JSON shows exactly one entry in info.Children whose Info.Filename differs from the top-level info.Filename — typically a qcow2 with a backing file, an external data file, or a VMDK extent, on QEMU >= 8.0 where Children are reported.

Common situations: Using a base image that was created with `qemu-img create -b backing.qcow2` (a backing-file chain) or converted from a VMDK with multiple extents; downloading a disk image that references an external data file; running with QEMU 8.0+ where children are detected but older tooling didn't flag them.

Related errors

• base disk (%#q) child must not have children of its own
• base disk (%#q) must not have multiple children: %+v
• configuration is nil
• field `vmOpts.qemu.minimumVersion` must be a semvar value, g
• mount type %#q is explicitly unsupported

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/879de77de35b07a9. Report an issue: GitHub.