{"record":{"id":"cb61129822329324","repo":"lima-vm/lima","slug":"directory-entry-q-not-found","errorCode":null,"errorMessage":"directory entry %#q not found","messagePattern":"directory entry %#q not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/apfs/chown.go","lineNumber":561,"sourceCode":"\t\t\t\tkOff, vOff := c.readTocEntry(blk, tocStart, i, isFixedKV)\n\t\t\t\tkeyStart := keyAreaStart + kOff\n\t\t\t\tkeyHeader := le.Uint64(blk[keyStart:])\n\n\t\t\t\tif keyHeader != targetKeyHeader {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\n\t\t\t\t// Parse the directory record key name.\n\t\t\t\tentryName := c.readDrecName(blk, keyStart+8)\n\t\t\t\tif entryName != name {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\n\t\t\t\t// Read file_id from j_drec_val_t (first 8 bytes of value).\n\t\t\t\tvalStart := valueAreaEnd - vOff\n\t\t\t\treturn le.Uint64(blk[valStart:]), nil\n\t\t\t}\n\t\t\treturn 0, fmt.Errorf(\"directory entry %#q not found\", name)\n\t\t}\n\n\t\t// Internal node: find the child to descend into.\n\t\t// The last key <= our target determines the child.\n\t\t// For DIR_REC keys with matching headers, we also compare the\n\t\t// name hash to find the correct subtree.\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\tcmp := c.compareDrecKey(blk, keyStart, targetKeyHeader, name, targetHash)\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}\n\t\t}\n","sourceCodeStart":543,"sourceCodeEnd":579,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/apfs/chown.go#L543-L579","documentation":"lookupDirEntry scanned the leaf node of the directory B-tree for the given parent CNID and name and found no matching directory record. This is a structured not-found error: the tree was healthy, but no entry with that name exists in that directory. resolvePath raises it for each path component it cannot resolve.","triggerScenarios":"Calling resolvePath with a path containing a component that does not exist in the target volume (e.g. resolving '/etc/hosts' on a volume without 'etc'), a name differing in case/normalization from what is stored, or looking up in the wrong parent directory after a wrong earlier component resolved to an unexpected inode.","commonSituations":"Hard-coded guest paths that don't exist in the mounted volume; NFD vs NFC Unicode normalization mismatch for accented filenames; typos in path constants; resolving against a snapshot that predates file creation.","solutions":["Check the path exists in the target volume (list the directory contents on the host)","Ensure names are NFD-normalized the way APFS stores them","Verify you are resolving against the intended volume/snapshot, not an older one","Handle the error by returning a clean not-found to your caller instead of treating it as corruption"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Confirm the path component exists before resolution\n// (e.g. list the directory via your own tooling or check on the host)\nif !knownPathExistsInVolume(volumeID, path) {\n    return fmt.Errorf(\"path %q not present in volume %s\", path, volumeID)\n}","typeGuard":"func isDirEntryNotFound(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"directory entry\") && strings.Contains(err.Error(), \"not found\")\n}","tryCatchPattern":"inode, err := c.resolvePath(root, omap, maxXID, path)\nif isDirEntryNotFound(err) {\n    return os.ErrNotExist // clean not-found for callers\n}","preventionTips":["Normalize paths to NFD before lookup (APFS stores NFD)","Do not hard-code guest paths; validate against actual volume contents","Remember snapshots may predate file creation"],"tags":["apfs","b-tree","not-found","directory","path-resolution"],"backgroundTag":"directory-entry-not-found","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}