{"record":{"id":"3c517bef53fc3ad5","repo":"hashicorp/nomad","slug":"boltdb-store-not-found-at-s-w","errorCode":null,"errorMessage":"BoltDB store not found at %s: %w","messagePattern":"BoltDB store not found at (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/migrate.go","lineNumber":186,"sourceCode":"\tif parent == nil {\n\t\tfor range sub {\n\t\t}\n\t\treturn\n\t}\n\tfor msg := range sub {\n\t\tselect {\n\t\tcase parent <- msg:\n\t\tdefault:\n\t\t\t// Drop message if consumer is slow to avoid blocking migration.\n\t\t}\n\t}\n}\n\nfunc preflightChecks(boltPath, walDir, raftDir string) error {\n\t// Verify the BoltDB file exists.\n\tboltInfo, err := os.Stat(boltPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"BoltDB store not found at %s: %w\", boltPath, err)\n\t}\n\n\t// Verify the WAL directory does not already exist.\n\tif _, err := os.Stat(walDir); err == nil {\n\t\treturn fmt.Errorf(\n\t\t\t\"WAL directory already exists at %s; remove it before retrying migration\",\n\t\t\twalDir)\n\t}\n\n\t// Check write permissions on raft directory.\n\ttestFile := filepath.Join(raftDir, \".permission-test\")\n\tif err := os.WriteFile(testFile, []byte(\"test\"), 0o600); err != nil {\n\t\treturn fmt.Errorf(\"insufficient write permissions in %s: %w\", raftDir, err)\n\t}\n\tos.Remove(testFile)\n\n\t// Check available disk space.\n\tusage, err := disk.Usage(raftDir)","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/migrate.go#L168-L204","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the correct raft data directory (the one containing raft.db) and re-run with that path.","If raft.db was already renamed to raft.db.migrated.<timestamp>, migration already succeeded — check for the wal directory and start the server.","Check parent-directory permissions/execute bits allowing stat traversal.","If the node never initialized raft, there is nothing to migrate — skip the migration."],"exampleFix":"// before\nerr := MigrateToWAL(ctx, \"/var/lib/nomad/wrong-dir\", progress)\n// after\nerr := MigrateToWAL(ctx, \"/var/lib/nomad/data/raft\", progress) // dir containing raft.db","handlingStrategy":"validation","validationCode":"boltPath := filepath.Join(raftDir, \"raft.db\")\nif fi, err := os.Stat(boltPath); err != nil || fi.IsDir() {\n    // check for an already-migrated backup before failing\n    matches, _ := filepath.Glob(boltPath + \".migrated.*\")\n    if len(matches) > 0 {\n        return fmt.Errorf(\"migration already completed: %s (wal/ should exist)\", matches[0])\n    }\n    return fmt.Errorf(\"no BoltDB store at %s; verify raftDir\", boltPath)\n}","typeGuard":null,"tryCatchPattern":"err := raftutil.MigrateToWAL(ctx, raftDir, progress)\nif err != nil && strings.Contains(err.Error(), \"BoltDB store not found\") {\n    // verify raftDir points at the directory containing raft.db before retrying\n}","preventionTips":["Pass the exact raft data directory that contains raft.db (Nomad data-dir/raft).","Check for raft.db.migrated.* backups — migration may have already run.","Run migration from the node itself with absolute paths, not relative paths.","Confirm parent-directory traversal permissions for the service user."],"tags":["filesystem","preflight","missing-file","migration"],"backgroundTag":"file-not-found","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}