{"record":{"id":"4526e19c9753f05a","repo":"lima-vm/lima","slug":"resolving-filesystem-root-tree-oid-d-w","errorCode":null,"errorMessage":"resolving filesystem root tree OID %d: %w","messagePattern":"resolving filesystem root tree OID (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/apfs/chown.go","lineNumber":34,"sourceCode":"\n// Chown sets the owner and group of files on an unmounted APFS disk image.\n// volumeRole selects the target volume (e.g., VolRoleData).\n// Paths are relative to the volume root (e.g., \"Library/LaunchDaemons/foo.plist\").\nfunc Chown(diskPath string, volumeRole uint16, uid, gid uint32, paths ...string) error {\n\tc, err := openContainer(diskPath)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer c.close()\n\n\tvol, err := c.findVolume(volumeRole)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfsRootPhys, err := c.omapLookup(vol.omapTreeAddr, vol.rootTreeOID, vol.latestXID)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"resolving filesystem root tree OID %d: %w\", vol.rootTreeOID, err)\n\t}\n\n\tfor _, path := range paths {\n\t\tinodeNum, err := c.resolvePath(fsRootPhys, vol.omapTreeAddr, vol.latestXID, path)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"resolving path %#q: %w\", path, err)\n\t\t}\n\t\tif err := c.chownInode(fsRootPhys, vol.omapTreeAddr, vol.latestXID, inodeNum, uid, gid); err != nil {\n\t\t\treturn fmt.Errorf(\"chown inode %d (%#q): %w\", inodeNum, path, err)\n\t\t}\n\t}\n\treturn nil\n}\n\n// container holds the open disk image file, the byte offset where\n// the APFS container starts (nonzero for GPT-partitioned disks),\n// and the APFS block size.\ntype container struct {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/apfs/chown.go#L16-L52","documentation":"Thrown by pkg/apfs.Chown when the volume's OMAP B-tree lookup fails to resolve the filesystem root tree virtual OID (vol.rootTreeOID) to a physical block address at transaction vol.latestXID. The underlying omapLookup error (I/O failure, checksum failure, missing omap entry) is wrapped with the root tree OID for diagnostics. This means the raw APFS disk could not be navigated to the volume's root filesystem B-tree.","triggerScenarios":"Calling apfs.Chown(diskPath, volumeRole, uid, gid, paths...) on a disk image whose volume omap lacks an entry for the root tree OID at the latest transaction ID, whose omap blocks fail checksum verification, or which cannot be read (I/O error, truncated image).","commonSituations":"Operating on a truncated or corrupted disk image; the volume was modified/snapshotted so the omap entry for the recorded XID is absent; pointing Chown at a non-APFS or unsupported image that still passed the superblock magic check; stale snapshot state where latestXID no longer matches omap contents.","solutions":["Verify the disk image is complete and uncorrupted (re-copy or re-export the image).","Ensure the volume is not actively being modified/snapshotted while Chown runs; work on a stable, unmounted copy.","Confirm the volumeRole passed to Chown matches a role that exists in the image (e.g. VolRoleData).","Check the image is a genuine APFS container (raw or GPT-partitioned); re-create with APFS if not."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fi, err := os.Stat(diskPath)\nif err != nil || fi.Size() < 4096 {\n    return fmt.Errorf(\"disk image %q missing or too small\", diskPath)\n}","typeGuard":null,"tryCatchPattern":"if err := apfs.Chown(disk, role, uid, gid, paths...); err != nil {\n    if strings.Contains(err.Error(), \"resolving filesystem root tree OID\") {\n        // image corrupt/snapshotted: obtain a fresh stable copy before retrying\n    }\n    return err\n}","preventionTips":["Operate only on unmounted, quiescent copies of the image.","Verify image integrity (size, checksum) before calling Chown.","Do not run against images with pending snapshots or active writers."],"tags":["apfs","disk-image","filesystem-internals"],"backgroundTag":"apfs-omap-lookup-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}