lima-vm/lima · error

no volume with role %#x found

Error message

no volume with role %#x found

What it means

findVolume scanned all nxMaxFileSystems volume slots in the container superblock and none of the resolvable, valid volume superblocks had the requested role. This is a lookup failure for the volumeRole argument passed to Chown, not data corruption. Common APFS roles include system (1), data (2), and preboot/recovery/VM roles.

Source

Thrown at pkg/apfs/chown.go:287

		}
		if le.Uint32(volBlock[apfsMagicOff:]) != apfsMagic {
			continue
		}
		volRole := le.Uint16(volBlock[apfsRoleOff:])
		if volRole == role {
			omapAddr := le.Uint64(volBlock[apfsOmapOIDOff:])
			omapBlock, err := c.readBlock(omapAddr)
			if err != nil {
				return nil, fmt.Errorf("reading volume omap: %w", err)
			}
			return &volumeInfo{
				omapTreeAddr: le.Uint64(omapBlock[omapTreeOIDOff:]),
				rootTreeOID:  le.Uint64(volBlock[apfsRootTreeOIDOff:]),
				latestXID:    le.Uint64(volBlock[objXIDOff:]),
			}, nil
		}
	}
	return nil, fmt.Errorf("no volume with role %#x found", role)
}

// omapLookup searches the omap B-tree for a virtual OID, returning
// the physical address from the entry with the highest xid <= maxXID.
func (c *container) omapLookup(omapTreeAddr, oid, maxXID uint64) (uint64, error) {
	blk, err := c.readBlock(omapTreeAddr)
	if err != nil {
		return 0, err
	}

	for {
		if verifyChecksum(blk) != nil {
			return 0, errors.New("omap node checksum failed")
		}
		if err := verifyBTreeNodeType(blk); err != nil {
			return 0, fmt.Errorf("omap node: %w", err)
		}
		flags := le.Uint16(blk[btnFlagsOff:])

View on GitHub (pinned to dd909d0973)

Solutions

1. Verify the image actually contains a volume with the requested role (e.g. inspect with diskutil on a macOS host).
2. Use the correct role constant for your image layout (system vs data volume).
3. If unsure of roles, enumerate volumes by trying each known role constant or dumping the container's volume list.
4. Confirm you opened the correct disk image, not another container.
5. If the role you need doesn't exist, create it (e.g. via diskutil apfs addVolume) before running Chown.

Example fix

// before
err := apfs.Chown(diskPath, 4 /* guessed role */, uid, gid, paths...)
// after
err := apfs.Chown(diskPath, apfs.VolRoleData, uid, gid, paths...)

// Only proceed if the role is one the image is known to contain.
var validRoles = map[uint16]bool{apfs.VolRoleSystem: true, apfs.VolRoleData: true}
if !validRoles[volumeRole] {
	return fmt.Errorf("role %#x not supported by this image layout", volumeRole)
}

if err := apfs.Chown(diskPath, volumeRole, uid, gid, paths...); err != nil {
	if strings.Contains(err.Error(), "no volume with role") {
		return fmt.Errorf("%w — check volumeRole constant and image layout", err)
	}
	return err
}

When it happens

Trigger: Calling apfs.Chown with a volumeRole that does not exist in the container, e.g. requesting VolRoleData on a single-volume container, or a role value that is a typo/unsupported constant.

Common situations: Working with minimal macOS images that only have a system volume, custom-built images with nonstandard roles, or passing a raw uint16 role value that doesn't match any volume in the target image.

Related errors

• unsupported shell %#q for Windows guest, must be one of %v
• resolving filesystem root tree OID %d: %w
• resolving path %#q: %w
• chown inode %d (%#q): %w
• open disk: %w

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