hashicorp/nomad · error

BoltDB store not found at

Error message

BoltDB store not found at %s: %w

What it means

preflightChecks stats <raftDir>/raft.db before anything else; this error wraps the os.Stat failure when the BoltDB store file is missing or unreadable. No files are created or modified, so it is a safe, immediate abort. It also fires when raft.db exists but cannot be stat'ed due to path or permission problems on parent directories.

Solutions

1. Verify the correct raft data directory (the one containing raft.db) and re-run with that path.
2. If raft.db was already renamed to raft.db.migrated.<timestamp>, migration already succeeded — check for the wal directory and start the server.
3. Check parent-directory permissions/execute bits allowing stat traversal.
4. If the node never initialized raft, there is nothing to migrate — skip the migration.

Example fix

// before
err := MigrateToWAL(ctx, "/var/lib/nomad/wrong-dir", progress)
// after
err := MigrateToWAL(ctx, "/var/lib/nomad/data/raft", progress) // dir containing raft.db

boltPath := filepath.Join(raftDir, "raft.db")
if fi, err := os.Stat(boltPath); err != nil || fi.IsDir() {
    // check for an already-migrated backup before failing
    matches, _ := filepath.Glob(boltPath + ".migrated.*")
    if len(matches) > 0 {
        return fmt.Errorf("migration already completed: %s (wal/ should exist)", matches[0])
    }
    return fmt.Errorf("no BoltDB store at %s; verify raftDir", boltPath)
}

err := raftutil.MigrateToWAL(ctx, raftDir, progress)
if err != nil && strings.Contains(err.Error(), "BoltDB store not found") {
    // verify raftDir points at the directory containing raft.db before retrying
}

When it happens

Trigger: os.Stat(raftDir/raft.db) returns an error: the file does not exist (wrong raftDir passed, fresh server that never ran, BoltDB already migrated/renamed), the path is a dangling symlink, or traversal permission denied on a parent directory.

Common situations: Operator passes the wrong -data-dir or runs migration on a non-server node; running migration twice — the second run finds raft.db renamed to raft.db.migrated.<ts>; typo in raftDir or relative path resolved from wrong working directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• WAL directory already exists at
• failed to clean task directories after failed migration
• failed to create migration marker
• failed to create WAL directory
• failed to open WAL store

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

Appendix: source

Thrown at helper/raftutil/migrate.go:186

	if parent == nil {
		for range sub {
		}
		return
	}
	for msg := range sub {
		select {
		case parent <- msg:
		default:
			// Drop message if consumer is slow to avoid blocking migration.
		}
	}
}

func preflightChecks(boltPath, walDir, raftDir string) error {
	// Verify the BoltDB file exists.
	boltInfo, err := os.Stat(boltPath)
	if err != nil {
		return fmt.Errorf("BoltDB store not found at %s: %w", boltPath, err)
	}

	// Verify the WAL directory does not already exist.
	if _, err := os.Stat(walDir); err == nil {
		return fmt.Errorf(
			"WAL directory already exists at %s; remove it before retrying migration",
			walDir)
	}

	// Check write permissions on raft directory.
	testFile := filepath.Join(raftDir, ".permission-test")
	if err := os.WriteFile(testFile, []byte("test"), 0o600); err != nil {
		return fmt.Errorf("insufficient write permissions in %s: %w", raftDir, err)
	}
	os.Remove(testFile)

	// Check available disk space.
	usage, err := disk.Usage(raftDir)

View on GitHub (pinned to 482b49bf1a)