lima-vm/lima · error

omap node: %w

Error message

omap node: %w

What it means

After passing checksum, each omap node's object type must be a B-tree node (root 0x02 or non-root 0x03). This error wraps the type-check failure from verifyBTreeNodeType, meaning the parser reached a block inside the omap tree that is not a B-tree node. It guards against following corrupted or misinterpreted child pointers.

Source

Thrown at pkg/apfs/chown.go:303

		}
	}
	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:])
		nkeys := le.Uint32(blk[btnNKeysOff:])
		tspOff := le.Uint16(blk[btnTableSpaceOff:])
		tspLen := le.Uint16(blk[btnTableSpaceOff+2:])

		tocStart := btnDataOff + uint32(tspOff)
		keyAreaStart := tocStart + uint32(tspLen)

		isLeaf := flags&btnodeLeaf != 0
		isFixedKV := flags&btnodeFixedKVSize != 0
		isRoot := flags&btnodeRoot != 0

		valueAreaEnd := c.blockSize
		if isRoot {
			valueAreaEnd -= btreeInfoSize
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Verify the image's APFS block size is supported (parser assumes >=4096 and fixed offsets).
2. Run fsck_apfs from a macOS host and retry on the repaired image.
3. Re-copy the image from a clean shutdown to rule out corruption.
4. If the image is from a much newer macOS, test whether the parser supports that on-disk version.
5. Check for concurrent modification of the image during the run.

if err := apfs.Chown(diskPath, role, uid, gid, paths...); err != nil {
	if strings.Contains(err.Error(), "omap node:") {
		return fmt.Errorf("omap structure not understood — image may use an unsupported APFS format: %w", err)
	}
	return err
}

When it happens

Trigger: Descent into an omap child node whose block is a different object type (e.g. a fs tree node, bitmap, or superblock) because a child pointer is corrupt, or because block-size/offset constants mismatch the on-disk format.

Common situations: Corrupted disk images, APFS containers from newer macOS versions with format changes this parser doesn't handle, or images with unusual block sizes (e.g. 8K/16K) breaking fixed offsets.

Related errors

• read block 0: %w
• reading container superblock: %w
• reading volume omap: %w
• omap node checksum failed
• reading omap child node: %w

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