hashicorp/nomad · error

failed to snapshot %s: %w

Error message

failed to snapshot %s: %w

What it means

AllocDir.Snapshot walks the allocation directory and writes each entry into a tar writer; if any individual entry fails during the walk, Snapshot aborts and returns this error identifying the offending path. Callers (server streaming a snapshot back for `nomad alloc fs`) surface it to the client, possibly after an in-band error marker on the stream fails too.

Source

Thrown at client/allocdir/alloc_dir.go:269

			return err
		}
		return nil
	}

	// Walk through all the top level directories and add the files and
	// directories in the archive
	for _, path := range rootPaths {
		if err := filepath.Walk(path, walkFn); err != nil {
			allocID := filepath.Base(a.AllocDir)
			if writeErr := writeError(tw, allocID, err); writeErr != nil {
				// This could be bad; other side won't know
				// snapshotting failed. It could also just mean
				// the snapshotting side closed the connect
				// prematurely and won't try to use the tar
				// anyway.
				a.logger.Warn("snapshotting failed and unable to write error marker", "error", writeErr)
			}
			return fmt.Errorf("failed to snapshot %s: %w", path, err)
		}
	}

	return nil
}

// Move other alloc directory's shared path and local dir to this alloc dir.
func (a *AllocDir) Move(other Interface, tasks []*structs.Task) error {
	a.mu.RLock()
	if !a.built {
		// Enforce the invariant that Build is called before Move
		a.mu.RUnlock()
		return fmt.Errorf("unable to move to %q - alloc dir is not built", a.AllocDir)
	}

	// Moving is slow and only reads immutable fields, so unlock during heavy IO
	a.mu.RUnlock()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Identify the failing path in the message and fix permissions or remove the problematic entry
2. Retry the snapshot when the task is idle
3. Stop/restart the task to quiesce writes then snapshot
4. Check disk health and free space

err := allocDir.Snapshot(w)
var pathErr string
if err != nil { pathErr = err.Error() } // message includes failing path; fix perms or retry when idle

When it happens

Trigger: Any per-entry failure while walking the alloc dir — unreadable directories (permissions), vanished files, symlink read failures — during `nomad alloc fs` snapshot or API snapshot calls.

Common situations: Tasks modifying/deleting files in the shared dir during snapshot; permission-restricted subdirectories; dying disks or quota-exceeded filesystems.

Related errors

• failed to open snapshot dir: %v
• plugin not executable
• error reading symlink: %v
• error creating file header: %w
• error creating task %q dir: %w

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