{"record":{"id":"ff11a94daf75edd3","repo":"hashicorp/nomad","slug":"failed-to-list-entries-v","errorCode":null,"errorMessage":"failed to list entries: %v","messagePattern":"failed to list entries: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/fs_endpoint.go","lineNumber":577,"sourceCode":"\tcase \"start\":\n\t\tnextIdx = 0\n\tcase \"end\":\n\t\tnextIdx = math.MaxInt64\n\t\toffset *= -1\n\tdefault:\n\t\treturn invalidOrigin\n\t}\n\n\tfor {\n\t\t// Logic for picking next file is:\n\t\t// 1) List log files\n\t\t// 2) Pick log file closest to desired index\n\t\t// 3) Open log file at correct offset\n\t\t// 3a) No error, read contents\n\t\t// 3b) If file doesn't exist, goto 1 as it may have been rotated out\n\t\tentries, err := fs.List(logPath)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to list entries: %v\", err)\n\t\t}\n\n\t\t// If we are not following logs, determine the max index for the logs we are\n\t\t// interested in so we can stop there.\n\t\tmaxIndex := int64(math.MaxInt64)\n\t\tif !follow {\n\t\t\t_, idx, _, err := findClosest(entries, maxIndex, 0, task, logType)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tmaxIndex = idx\n\t\t}\n\n\t\tlogEntry, idx, openOffset, err := findClosest(entries, nextIdx, offset, task, logType)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n","sourceCodeStart":559,"sourceCodeEnd":595,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/fs_endpoint.go#L559-L595","documentation":"Inside the client's log reading implementation (logsImpl), the filesystem wrapper fs.List() failed while enumerating the allocation's log files in logPath. The OS-level error is embedded via %v. This aborts the log streaming loop and propagates to the HTTP stream as an error frame.","triggerScenarios":"fs.List on the alloc's log directory fails — typically because the directory no longer exists (alloc GC'd, filesystem teardown raced the read), permission problems, or underlying I/O errors from the host FS.","commonSituations":"Reading logs while the allocation is being cleaned up on the client; overlay/scratch dir removed on node restart; disk full or permission changes in the client data dir; running the Nomad agent without sufficient privileges to its alloc dirs.","solutions":["Retry the log read; if the alloc was GC'd mid-read, re-resolve the allocation first.","Verify the client's data/alloc/<id>/alloc/logs directory exists and is readable by the Nomad agent.","Check the embedded OS error (e.g. 'no such file or directory' vs 'permission denied') and address the underlying cause.","Increase GC thresholds (client gc_max_allocs, job reschedule settings) if allocations disappear while being read."],"exampleFix":"// before\nentries, err := fs.List(logPath)\nif err != nil {\n    return fmt.Errorf(\"failed to list entries: %v\", err)\n}\n// after\nentries, err := fs.List(logPath)\nif err != nil {\n    if os.IsNotExist(err) {\n        return ErrLogDirGone // caller re-resolves alloc and retries\n    }\n    return fmt.Errorf(\"failed to list entries: %w\", err)\n}","handlingStrategy":"retry","validationCode":"a, _, err := client.Allocations().Info(allocID, nil)\nif err != nil || a.ClientStatus == \"lost\" || a.ClientStatus == \"complete\" {\n    return fmt.Errorf(\"skip log read; alloc state: %v\", a.ClientStatus)\n}","typeGuard":"func isListFailure(err error) bool {\n    return strings.Contains(err.Error(), \"failed to list entries\")\n}","tryCatchPattern":"if err := readLogs(); err != nil {\n    if isListFailure(err) {\n        time.Sleep(time.Second)\n        return readLogsWithReResolvedAlloc()\n    }\n    return err\n}","preventionTips":["Avoid reading logs during alloc teardown windows.","Check the wrapped OS error for the root cause (ENOENT vs EACCES).","Ensure the client data dir has correct ownership/permissions.","Tune GC settings so allocs aren't reclaimed while being read."],"tags":["nomad","client","logs","filesystem","io"],"backgroundTag":"log-file-read-failed","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"}