{"record":{"id":"97277495e5fd7d33","repo":"hashicorp/nomad","slug":"unable-to-read-rooted-allocation-directory","errorCode":null,"errorMessage":"unable to read rooted allocation directory","messagePattern":"unable to read rooted allocation directory","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/getter/util.go","lineNumber":365,"sourceCode":"// the dstDir. This is a destructive action; the contents of\n// srcDir are moved into dstDir.\nfunc mergeDirectories(at *os.Root, srcDir, dstDir string) error {\n\tvar entries []fs.DirEntry\n\tvar err error\n\tif runtime.GOOS == \"windows\" {\n\t\tdirFile, err := at.Open(srcDir)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tdefer dirFile.Close()\n\t\tentries, err = dirFile.ReadDir(-1)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t} else {\n\t\trd, ok := at.FS().(fs.ReadDirFS)\n\t\tif !ok {\n\t\t\treturn errors.New(\"unable to read rooted allocation directory\")\n\t\t}\n\t\tentries, err = rd.ReadDir(srcDir)\n\t}\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor _, entry := range entries {\n\t\tsrc := filepath.Join(srcDir, entry.Name())\n\t\tdst := filepath.Join(dstDir, entry.Name())\n\n\t\tsrcInfo, err := at.Stat(src)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tdstInfo, err := at.Stat(dst)\n\t\tif err != nil {","sourceCodeStart":347,"sourceCodeEnd":383,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/getter/util.go#L347-L383","documentation":"During artifact sandboxing, mergeDirectories walks a source directory of the rooted allocation directory by reading its entries. When the io/fs filesystem backing the rooted alloc dir does not implement fs.ReadDirFS (only file reading), the type assertion at.FS().(fs.ReadDirFS) fails and this error is returned: 'unable to read rooted allocation directory'. It means Nomad cannot enumerate directory entries, so directories cannot be merged into the task sandbox.","triggerScenarios":"Running the getter's runCmd path where mergeDirectories is invoked with a srcDir that must be listed, and the mounted fstype used for the rooted allocation directory lacks a ReadDir method (assertion in util.go:365 fails). Typically caused by an unusual/misconfigured filesystem for client dataDir or alloc mount, or a platform/OS-level limitation of the fstype in use.","commonSituations":"Nomad clients running on filesystems or mount options where directory listing on the alloc dir is restricted (e.g. certain overlay/network filesystems, permission fixes on client data_dir), or nonstandard client data_dir configuration. Permissions on the alloc dir can also surface as this failure path in some setups.","solutions":["Check host filesystem for client data_dir/alloc dir: run on a filesystem supporting normal readdir (local ext4/xfs); fix restrictive mount options or permissions","Verify the Nomad client user can read (r+x) the rooted alloc directory: chown/adjust permissions and restart the client","Remove stale/corrupt alloc directories under data_dir/alloc and let the client re-create them","If it persists, upgrade Nomad or file an issue — the fstype backing the alloc dir may not implement ReadDirFS on your platform"],"exampleFix":"# before: data_dir on a mount without directory read support for the client user\nclient { data_dir = \"/mnt/restricted-fs/nomad\" }\n# after: local filesystem with correct ownership\nclient { data_dir = \"/opt/nomad/data\" }\nsudo chown -R nomad:nomad /opt/nomad/data","handlingStrategy":"validation","validationCode":"// Go: verify the FS backing the alloc dir supports ReadDir before merging\nif _, ok := at.FS().(fs.ReadDirFS); !ok {\n\treturn errors.New(\"alloc dir fstype cannot list directories; check client data_dir filesystem\")\n}","typeGuard":"func canReadDir(fsys fs.FS) bool {\n\t_, ok := fsys.(fs.ReadDirFS)\n\treturn ok\n}","tryCatchPattern":"if err := mergeDirectories(src, dst); err != nil {\n\tif strings.Contains(err.Error(), \"unable to read rooted allocation directory\") {\n\t\t// check client data_dir filesystem/permissions, then re-run task\n\t\treturn fmt.Errorf(\"alloc dir unreadable (fstype/permissions): %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Put client data_dir on a standard local filesystem (ext4/xfs), not exotic overlay/network mounts","Ensure the Nomad client user has r+x on the rooted alloc directory tree","Clean stale alloc directories after client crashes or data_dir moves","Monitor client filesystem mount changes before/after infrastructure updates"],"tags":["filesystem","client","allocdir","io"],"backgroundTag":"filesystem-readdir-unsupported","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}