{"record":{"id":"1ba96fcba9047ecb","repo":"lima-vm/lima","slug":"omap-entry-for-oid-d-not-found","errorCode":null,"errorMessage":"omap entry for OID %d not found","messagePattern":"omap entry for OID (.+?) not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/apfs/chown.go","lineNumber":346,"sourceCode":"\t\t\tfor i := range nkeys {\n\t\t\t\tkOff, vOff := c.readTocEntry(blk, tocStart, i, isFixedKV)\n\t\t\t\tkeyStart := keyAreaStart + kOff\n\t\t\t\tentryOID := le.Uint64(blk[keyStart:])\n\t\t\t\tentryXID := le.Uint64(blk[keyStart+8:])\n\n\t\t\t\tif entryOID == oid && entryXID <= maxXID {\n\t\t\t\t\t// Value: ov_flags(4) + ov_size(4) + ov_paddr(8).\n\t\t\t\t\tvalStart := valueAreaEnd - vOff\n\t\t\t\t\tphysAddr := le.Uint64(blk[valStart+8:])\n\t\t\t\t\tif !found || entryXID > bestXID {\n\t\t\t\t\t\tbestPhysAddr = physAddr\n\t\t\t\t\t\tbestXID = entryXID\n\t\t\t\t\t\tfound = true\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tif !found {\n\t\t\t\treturn 0, fmt.Errorf(\"omap entry for OID %d not found\", oid)\n\t\t\t}\n\t\t\treturn bestPhysAddr, nil\n\t\t}\n\n\t\t// Internal node: find the last key <= (oid, maxXID) and descend.\n\t\tchildIdx := uint32(0)\n\t\tfor i := range nkeys {\n\t\t\tkOff, _ := c.readTocEntry(blk, tocStart, i, isFixedKV)\n\t\t\tkeyStart := keyAreaStart + kOff\n\t\t\tentryOID := le.Uint64(blk[keyStart:])\n\t\t\tentryXID := le.Uint64(blk[keyStart+8:])\n\n\t\t\tcmp := compareOmapKey(entryOID, entryXID, oid, maxXID)\n\t\t\tif cmp <= 0 {\n\t\t\t\tchildIdx = i\n\t\t\t} else {\n\t\t\t\tbreak\n\t\t\t}","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/apfs/chown.go#L328-L364","documentation":"omapLookup searched the omap leaf node for an entry whose key is (oid, xid <= maxXID) and found none. The omap maps virtual object IDs to physical addresses; if the requested virtual OID has no mapping at or below the given transaction ID, its physical address cannot be resolved. In findVolume unresolvable volumes are skipped silently; via lookupDirEntry/chownInode the error propagates wrapped as 'resolving child OID N'.","triggerScenarios":"Resolving a virtual OID that was deleted (purged by a snapshot/trim), passing a maxXID lower than any entry's xid for that OID (e.g. using a stale containerXID while the volume tree was rewritten), or a corrupt leaf search path.","commonSituations":"Images with purged snapshots, using a stale XID captured from an older superblock while newer transactions exist, or referencing OIDs from a different volume's omap.","solutions":["Ensure the maxXID passed is the latest XID from the corresponding superblock (findVolume already uses vol.latestXID; check custom code paths).","Re-take the image from a clean shutdown so omap entries are consistent.","Run fsck_apfs on the image to rebuild omap consistency.","Avoid purging snapshots/trimming the image before running Chown.","If the OID belongs to a different volume, resolve it through that volume's omap instead."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := apfs.Chown(diskPath, role, uid, gid, paths...); err != nil {\n\tif strings.Contains(err.Error(), \"omap entry for OID\") {\n\t\t// retry with a freshly-taken image; stale XIDs/purged OIDs do not recover in place\n\t\treturn fmt.Errorf(\"virtual OID unresolvable; retake the image from a clean shutdown: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Don't purge snapshots or TRIM the image before running Chown.","Take images from cleanly shut-down VMs so XIDs are consistent.","Don't reuse OMAP addresses/XIDs captured from older image versions.","If you call lower-level APIs, always pass the latest XID from the corresponding superblock."],"tags":["apfs","omap","oid-resolution"],"backgroundTag":"apfs-omap-entry-not-found","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}