hashicorp/nomad · error

error reading symlink: %v

Error message

error reading symlink: %v

What it means

While building a tar snapshot of the allocation directory, AllocDir walks files and, for symlinks, calls os.Readlink to record the link target. If Readlink fails (the entry disappeared mid-walk or the path is not actually a symlink despite the mode bit), the walk is aborted with this wrapped error. It usually indicates a filesystem race or permission problem.

Source

Thrown at client/allocdir/alloc_dir.go:225

	tw := tar.NewWriter(w)
	defer tw.Close()

	walkFn := func(path string, fileInfo os.FileInfo, err error) error {
		if err != nil {
			return err
		}

		// Include the path of the file name relative to the alloc dir
		// so that we can put the files in the right directories
		relPath, err := filepath.Rel(a.AllocDir, path)
		if err != nil {
			return err
		}
		link := ""
		if fileInfo.Mode()&os.ModeSymlink != 0 {
			target, err := os.Readlink(path)
			if err != nil {
				return fmt.Errorf("error reading symlink: %v", err)
			}
			link = target
		}
		hdr, err := tar.FileInfoHeader(fileInfo, link)
		if err != nil {
			return fmt.Errorf("error creating file header: %w", err)
		}
		hdr.Name = relPath
		if err := tw.WriteHeader(hdr); err != nil {
			return err
		}

		// If it's a directory or symlink we just write the header into the tar
		if fileInfo.IsDir() || (fileInfo.Mode()&os.ModeSymlink != 0) {
			return nil
		}

		// Write the file into the archive

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Retry the snapshot; transient races usually clear
2. Quiesce the task / stop writes to the alloc dir before snapshotting
3. Check filesystem permissions on the symlink path
4. Exclude volatile paths from the snapshot

err := allocDir.Snapshot(w)
if err != nil && strings.Contains(err.Error(), "error reading symlink") {
  // transient race: retry snapshot after quiescing the task
}

When it happens

Trigger: A file that appeared as a symlink in the mode bits was deleted or replaced between the lstat and Readlink calls; permissions deny reading the link; reading a special filesystem where mode bits mislead.

Common situations: Snapshotting an alloc dir while a task is actively creating/removing symlinks (temp files, socket links); NFS/network filesystems with unstable entries; containers modifying the shared dir during snapshot.

Related errors

• error creating file header: %w
• failed to snapshot %s: %w
• failed to resolve alloc directory: %w
• Couldn't read the file information %v: %w
• Couldn't resolve symlink for %v: %w

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