hashicorp/nomad · error

failed to open snapshot dir: %v

Error message

failed to open snapshot dir: %v

What it means

NewFSM wraps the error from raft.NewFileSnapshotStoreWithLogger when the snapshots directory under the data path cannot be created or opened. The raft library is closed first to release the state store. Commonly a permissions or path problem.

Source

Thrown at helper/raftutil/fsm.go:62

func NewFSM(p string) (*FSMHelper, error) {
	// Auto-detect the backend: look for wal/ directory first, then raft.db.
	storePath, err := FindRaftStore(p)
	if err != nil {
		return nil, fmt.Errorf("failed to find raft store in %v: %v", p, err)
	}

	store, firstIdx, lastIdx, err := RaftStateInfo(storePath)
	if err != nil {
		return nil, fmt.Errorf("failed to open raft store %v: %v", storePath, err)
	}

	logger := hclog.L()

	snaps, err := raft.NewFileSnapshotStoreWithLogger(p, 1000, logger)
	if err != nil {
		store.Close()
		return nil, fmt.Errorf("failed to open snapshot dir: %v", err)
	}

	fsm, err := dummyFSM(logger)
	if err != nil {
		store.Close()
		return nil, err
	}

	return &FSMHelper{
		path:   p,
		logger: logger,
		store:  store,
		fsm:    fsm,
		snaps:  snaps,

		logFirstIdx: firstIdx,
		logLastIdx:  lastIdx,
		nextIdx:     uint64(1),

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check permissions on the data dir and its snapshots/ subdirectory (needs read/write)
2. Ensure the filesystem is writable and has free space
3. Verify the data path is a directory, not a regular file

Example fix

// before
fsm, err := raftutil.NewFSM(dataDir)
// after
snapDir := filepath.Join(dataDir, "snapshots")
if err := os.MkdirAll(snapDir, 0o700); err != nil {
    return fmt.Errorf("cannot prepare snapshot dir %s: %w", snapDir, err)
}
fsm, err := raftutil.NewFSM(dataDir)

snapDir := filepath.Join(dataDir, "snapshots")
if err := os.MkdirAll(snapDir, 0o700); err != nil {
    return fmt.Errorf("snapshot dir not creatable/writable: %w", err)
}
if err := checkFreeSpace(dataDir, 64*1024*1024); err != nil {
    return err
}

if err := raftutil.NewFSM(dataDir); err != nil {
    if strings.Contains(err.Error(), "failed to open snapshot dir") {
        return fmt.Errorf("check permissions/writability of %s/snapshots: %w", dataDir, err)
    }
    return err
}

When it happens

Trigger: Calling NewFSM when the snapshots/ directory cannot be created (read-only filesystem, permission denied, path is a file not a directory) or existing snapshot files are unreadable/corrupt.

Common situations: Running the tool as a non-root user against a root-owned data dir; mounting the data dir read-only; disk full preventing snapshot store creation.

Related errors

• failed to snapshot %s: %w
• error creating directory: %w
• error setting directory permission mode: %w
• cannot create copy - %s
• failed to scan plugin directory %q: %v

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