{"record":{"id":"a0e59012bb74f5aa","repo":"lima-vm/lima","slug":"filesystem-b-tree-node-checksum-failed","errorCode":null,"errorMessage":"filesystem B-tree node checksum failed","messagePattern":"filesystem B-tree node checksum failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/apfs/chown.go","lineNumber":519,"sourceCode":"\t\tcnid = fileID\n\t}\n\treturn cnid, nil\n}\n\n// lookupDirEntry searches the filesystem B-tree for a directory record\n// matching parentCNID and name, returning the file_id from j_drec_val_t.\nfunc (c *container) lookupDirEntry(fsRootPhys, omapTreeAddr, maxXID, parentCNID uint64, name string) (uint64, error) {\n\ttargetKeyHeader := (uint64(apfsTypeDirRec) << objTypeShift) | (parentCNID & objIDMask)\n\ttargetHash := drecNameHash(name)\n\n\tblk, err := c.readBlock(fsRootPhys)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\n\tfor {\n\t\tif verifyChecksum(blk) != nil {\n\t\t\treturn 0, errors.New(\"filesystem B-tree node checksum failed\")\n\t\t}\n\t\tif err := verifyBTreeNodeType(blk); err != nil {\n\t\t\treturn 0, fmt.Errorf(\"filesystem B-tree node: %w\", err)\n\t\t}\n\t\tflags := le.Uint16(blk[btnFlagsOff:])\n\t\tnkeys := le.Uint32(blk[btnNKeysOff:])\n\t\ttspOff := le.Uint16(blk[btnTableSpaceOff:])\n\t\ttspLen := le.Uint16(blk[btnTableSpaceOff+2:])\n\n\t\ttocStart := btnDataOff + uint32(tspOff)\n\t\tkeyAreaStart := tocStart + uint32(tspLen)\n\n\t\tisLeaf := flags&btnodeLeaf != 0\n\t\tisFixedKV := flags&btnodeFixedKVSize != 0\n\t\tisRoot := flags&btnodeRoot != 0\n\n\t\tvalueAreaEnd := c.blockSize\n\t\tif isRoot {","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/apfs/chown.go#L501-L537","documentation":"This error is thrown by lookupDirEntry when the on-disk checksum (fletcher/CRC) of an APFS B-tree node block read during a directory-entry lookup does not match. The library verifies every B-tree node it touches before parsing it, because a corrupt node would produce garbage directory entries. It indicates block-level corruption of the filesystem tree being walked, not a caller mistake.","triggerScenarios":"Calling resolvePath (which calls lookupDirEntry) on a volume whose directory B-tree blocks were corrupted on disk: partial/interrupted write, bit rot, bad disk sector, or reading a stale/mismatched physical block address after the tree was rebalanced or the snapshot changed under the reader.","commonSituations":"Reading an APFS disk image that was truncated or copied while the host was writing; inspecting a snapshot after the underlying disk developed bad sectors; mounting with a wrong omap/XID so a stale block (old checksum context) is read.","solutions":["Run fsck_apfs on the volume/image to detect and repair the corrupt B-tree node","Restore the disk image or volume from a backup/snapshot taken before the corruption","Verify the image file is not truncated and its size matches the APFS container description","Re-run the lookup with the correct max XID / omap tree so current, not stale, blocks are resolved"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Verify image integrity before walking\nif fi, err := os.Stat(imagePath); err != nil || fi.Size() < expectedMinSize {\n    return fmt.Errorf(\"image %s missing or truncated\", imagePath)\n}","typeGuard":"func isBTreeChecksumFailure(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"B-tree node checksum failed\")\n}","tryCatchPattern":"inode, err := c.resolvePath(root, omap, maxXID, path)\nif isBTreeChecksumFailure(err) {\n    // block-level corruption: surface as fatal, suggest fsck_apfs\n    return fmt.Errorf(\"volume corrupt, run fsck_apfs: %w\", err)\n}","preventionTips":["Always copy disk images while the source VM is shut down","Keep checksums/verified backups of images before operating on them","Run fsck_apfs before read-modify-write operations on an image","Use storage that reports sector errors; monitor disk health"],"tags":["apfs","b-tree","checksum","corruption","disk"],"backgroundTag":"b-tree-node-checksum-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}