hashicorp/nomad · error

failed to find raft store in %v: %v

Error message

failed to find raft store in %v: %v

What it means

NewFSM wraps the error from FindRaftStore when it cannot locate a valid Raft backend (wal/ directory or raft.db file) under the given data path. The data directory either has no recognizable Raft store or is unreadable.

Source

Thrown at helper/raftutil/fsm.go:49

	logger hclog.Logger

	// nomad state
	store RaftStore
	fsm   nomadFSM
	snaps *raft.FileSnapshotStore

	// raft
	logFirstIdx uint64
	logLastIdx  uint64
	nextIdx     uint64
}

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()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the path is a Nomad SERVER data dir containing raft.db or a wal/ subdirectory
2. Check filesystem permissions on the data dir (read/execute for the running user)
3. Confirm the server has been initialized/bootstrapped (fresh dirs have no raft store)

Example fix

// before
fsm, err := raftutil.NewFSM(dataDir)
// after
if _, err := os.Stat(filepath.Join(dataDir, "raft.db")); os.IsNotExist(err) {
    if _, err := os.Stat(filepath.Join(dataDir, "wal")); os.IsNotExist(err) {
        return nil, fmt.Errorf("%s is not a server data dir: no raft.db or wal/", dataDir)
    }
}
fsm, err := raftutil.NewFSM(dataDir)

func hasRaftStore(dataDir string) error {
    for _, p := range []string{"raft.db", "wal"} {
        if fi, err := os.Stat(filepath.Join(dataDir, p)); err == nil && !fi.IsDir() || fi != nil && fi.IsDir() {
            return nil
        }
    }
    return fmt.Errorf("%s has no raft.db or wal/ — not a server data dir", dataDir)
}

if err := raftutil.NewFSM(dataDir); err != nil {
    if strings.Contains(err.Error(), "failed to find raft store") {
        return fmt.Errorf("path %q is not a Nomad server data dir: %w", dataDir, err)
    }
    return err
}

When it happens

Trigger: Calling NewFSM with a path that is not a Nomad server data dir, an empty directory, a client data dir (no raft state), or a path with wrong permissions that prevents detection of wal/ or raft.db.

Common situations: Pointing raftutil tooling at a Nomad client directory instead of a server data dir; running as a user without read access to /var/nomad/data; pointing at a fresh data dir that was never bootstrapped.

Related errors

• failed to open raft store %v: %v
• failed to open snapshot dir: %v
• failed to read log entry at index %d: %v
• failed to stat %s: %v
• failed to create WAL directory: %v

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