hashicorp/nomad · error

error creating file header: %w

Error message

error creating file header: %w

What it means

During tar snapshot construction, tar.FileInfoHeader converts the walked file's os.FileInfo into a tar header. If the OS rejects the header construction (unsupported file type, stat inconsistency, or a corrupt/unusual mode), the snapshot returns this wrapped error. It is rare and indicates an OS/filesystem-level incompatibility.

Source

Thrown at client/allocdir/alloc_dir.go:231

		}

		// 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
		file, err := os.Open(path)
		if err != nil {
			return err
		}
		defer file.Close()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Retry the snapshot after transient races clear
2. Exclude problematic paths (sockets, devices) from snapshot scope
3. Update Go/runtime to pick up tar fixes
4. Check filesystem health (fsck) if persistent

err := allocDir.Snapshot(w)
if err != nil && strings.Contains(err.Error(), "error creating file header") {
  // inspect the file type at the reported path; skip or handle special files
}

When it happens

Trigger: os.FileInfo inconsistent with the on-disk entry (file replaced between lstat and header creation); exotic file types unsupported by tar; platform-specific header limitations.

Common situations: Snapshotting while tasks churn the directory; unusual filesystems (FUSE, 9p) reporting odd modes; Go/tar version edge cases with special files.

Related errors

• error reading symlink: %v
• failed to snapshot %s: %w
• Unable to tar files - %v
• unable to read rooted allocation directory
• plugin not found

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