lima-vm/lima · critical

reading container superblock: %w

Error message

reading container superblock: %w

What it means

This error is returned by findVolume when it cannot locate the newest valid APFS container superblock via latestSuperblock. The container superblock is required to find the container omap and enumerate volumes, so without it no operation can proceed. It is always a wrapper around a lower-level cause (checksum failure, unreadable block, or no valid superblock in the checkpoint descriptor area).

Source

Thrown at pkg/apfs/chown.go:239

			continue
		}
		xid := le.Uint64(blk[objXIDOff:])
		if xid > bestXID {
			bestXID = xid
			bestBlock = blk
		}
	}
	if bestBlock == nil {
		return nil, errors.New("no valid container superblock found in checkpoint area")
	}
	return bestBlock, nil
}

// findVolume locates the volume with the given role.
func (c *container) findVolume(role uint16) (*volumeInfo, error) {
	sb, err := c.latestSuperblock()
	if err != nil {
		return nil, fmt.Errorf("reading container superblock: %w", err)
	}

	// Read the container omap to resolve volume virtual OIDs.
	containerOmapAddr := le.Uint64(sb[nxOmapOIDOff:])
	containerOmap, err := c.readBlock(containerOmapAddr)
	if err != nil {
		return nil, fmt.Errorf("reading container omap at %d: %w", containerOmapAddr, err)
	}
	containerOmapTreeAddr := le.Uint64(containerOmap[omapTreeOIDOff:])

	containerXID := le.Uint64(sb[objXIDOff:])

	for i := range nxMaxFileSystems {
		off := nxFSOIDOff + i*8
		volOID := le.Uint64(sb[off:])
		if volOID == 0 {
			continue
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Verify the diskPath points to a raw APFS image (or GPT disk containing an APFS container), not a VM disk format or a filesystem image of another type.
2. Check block 0 and the checkpoint descriptor area with a hex dump to confirm APFS magic 'NXSB' is present.
3. Re-copy or re-export the disk image; the source may be truncated or corrupted.
4. Shut down the VM/instance cleanly before taking the image so the checkpoint area is consistent.
5. Run fsck_apfs on the image from a macOS host to repair container metadata.

Example fix

// before
err := apfs.Chown("/vms/mac/disk.qcow2", apfs.VolRoleData, 501, 20, "Library/LaunchDaemons/x.plist")
// after
// convert to raw first: qemu-img convert -O raw disk.qcow2 disk.raw
err := apfs.Chown("/vms/mac/disk.raw", apfs.VolRoleData, 501, 20, "Library/LaunchDaemons/x.plist")

func looksLikeRawAPFSImage(path string) error {
	f, err := os.Open(path)
	if err != nil { return err }
	defer f.Close()
	hdr := make([]byte, 4096)
	if _, err := f.ReadAt(hdr, 0); err != nil { return err }
	if string(hdr[32:36]) == "NXSB" { return nil } // magic at nxMagicOff
	// else require a GPT with an APFS partition
	return errors.New("not a raw APFS container image")
}

if err := apfs.Chown(diskPath, role, uid, gid, paths...); err != nil {
	if strings.Contains(err.Error(), "reading container superblock") {
		return fmt.Errorf("%w: verify %s is a raw APFS image and not truncated", err, diskPath)
	}
	return err
}

When it happens

Trigger: Calling apfs.Chown (or anything invoking findVolume) on a disk image whose checkpoint descriptor area contains no block passing checksum, magic, and objectTypeNXSuperblock validation, or whose block 0 fails its fletcher checksum, or whose blocks cannot be read from the image file.

Common situations: Pointing Chown at a non-APFS image (ext4, qcow2 without raw layout), a truncated or corrupted disk image, an image written while the guest was still running, or an APFS container formatted by a newer macOS with structures this parser does not understand.

Related errors

• read block 0: %w
• reading volume omap: %w
• resolving filesystem root tree OID %d: %w
• resolving path %#q: %w
• chown inode %d (%#q): %w

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