What causes "failed to list entries: %v" in hashicorp/nomad?

Retry the log read; if the alloc was GC'd mid-read, re-resolve the allocation first.

failed to list entries: %v

Error message

failed to list entries: %v

What it means

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.

Source

Thrown at client/fs_endpoint.go:577

	case "start":
		nextIdx = 0
	case "end":
		nextIdx = math.MaxInt64
		offset *= -1
	default:
		return invalidOrigin
	}

	for {
		// Logic for picking next file is:
		// 1) List log files
		// 2) Pick log file closest to desired index
		// 3) Open log file at correct offset
		// 3a) No error, read contents
		// 3b) If file doesn't exist, goto 1 as it may have been rotated out
		entries, err := fs.List(logPath)
		if err != nil {
			return fmt.Errorf("failed to list entries: %v", err)
		}

		// If we are not following logs, determine the max index for the logs we are
		// interested in so we can stop there.
		maxIndex := int64(math.MaxInt64)
		if !follow {
			_, idx, _, err := findClosest(entries, maxIndex, 0, task, logType)
			if err != nil {
				return err
			}
			maxIndex = idx
		}

		logEntry, idx, openOffset, err := findClosest(entries, nextIdx, offset, task, logType)
		if err != nil {
			return err
		}

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before
entries, err := fs.List(logPath)
if err != nil {
    return fmt.Errorf("failed to list entries: %v", err)
}
// after
entries, err := fs.List(logPath)
if err != nil {
    if os.IsNotExist(err) {
        return ErrLogDirGone // caller re-resolves alloc and retries
    }
    return fmt.Errorf("failed to list entries: %w", err)
}

Defensive patterns

Strategy: retry

Validate before calling

a, _, err := client.Allocations().Info(allocID, nil)
if err != nil || a.ClientStatus == "lost" || a.ClientStatus == "complete" {
    return fmt.Errorf("skip log read; alloc state: %v", a.ClientStatus)
}

Type guard

func isListFailure(err error) bool {
    return strings.Contains(err.Error(), "failed to list entries")
}

Try / catch

if err := readLogs(); err != nil {
    if isListFailure(err) {
        time.Sleep(time.Second)
        return readLogsWithReResolvedAlloc()
    }
    return err
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/ff11a94daf75edd3. Report an issue: GitHub.