{"record":{"id":"a41dcec6f516d936","repo":"hashicorp/nomad","slug":"failed-to-open-boltdb-store-w","errorCode":null,"errorMessage":"failed to open BoltDB store: %w","messagePattern":"failed to open BoltDB store: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/migrate.go","lineNumber":85,"sourceCode":"\n\tsendProgress(progress, \"pre-flight checks passed\")\n\n\t// Create marker file to detect if server accidentally starts during migration.\n\tif err := os.WriteFile(markerPath, []byte(time.Now().Format(time.RFC3339)), 0o600); err != nil {\n\t\treturn fmt.Errorf(\"failed to create migration marker: %w\", err)\n\t}\n\tdefer os.Remove(markerPath) // Clean up marker on completion or failure.\n\n\t// Open the source BoltDB store.\n\tsrc, err := raftboltdb.New(raftboltdb.Options{\n\t\tPath: boltPath,\n\t\tBoltOptions: &bbolt.Options{\n\t\t\tTimeout: 5 * time.Second,\n\t\t},\n\t\tMsgpackUseNewTimeFormat: true,\n\t})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to open BoltDB store: %w\", err)\n\t}\n\n\t// Create the destination WAL store.\n\tif err := os.MkdirAll(walDir, 0o700); err != nil {\n\t\tsrc.Close()\n\t\treturn fmt.Errorf(\"failed to create WAL directory: %w\", err)\n\t}\n\n\tdst, err := raftwal.Open(walDir)\n\tif err != nil {\n\t\tsrc.Close()\n\t\tcleanupWAL(walDir)\n\t\treturn fmt.Errorf(\"failed to open WAL store: %w\", err)\n\t}\n\n\t// Copy logs.\n\tlogProgress := make(chan string, 64)\n\twg.Add(1)","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/migrate.go#L67-L103","documentation":"MigrateToWAL wraps the error from raftboltdb.New when the source BoltDB store (raft.db) cannot be opened with a 5-second lock timeout. Typically the file is locked by a running server, missing, or corrupt.","triggerScenarios":"Calling MigrateToWAL while the Nomad server still holds the BoltDB lock (times out after 5s), raft.db doesn't exist (NoBoltDB case), permissions deny access, or the DB file is corrupt.","commonSituations":"Forgetting to stop the Nomad server before migrating; pointing the tool at a WAL-only data dir with no raft.db; running as a user without read access to raft.db.","solutions":["Stop the Nomad server process so the BoltDB file lock is released, then rerun","Verify raft.db exists in the data dir (this tool migrates BoltDB to WAL; a WAL-only dir cannot be a source)","Check permissions on raft.db; if corrupt, restore from backup or snapshot before migrating"],"exampleFix":"// before\nsystemctl start nomad && nomad-operator migrate-to-wal /var/nomad/data // lock contention\n// after\nsystemctl stop nomad\n# wait for lock release, then:\nraftutil.MigrateToWAL(\"/var/nomad/data\")\nsystemctl start nomad","handlingStrategy":"validation","validationCode":"boltPath := filepath.Join(dataDir, \"raft.db\")\nif _, err := os.Stat(boltPath); os.IsNotExist(err) {\n    return fmt.Errorf(\"no raft.db at %s — nothing to migrate\", boltPath)\n}\nif err := tryLockBoltDB(boltPath, 1*time.Second); err != nil {\n    return fmt.Errorf(\"raft.db is locked — stop the nomad server first\")\n}","typeGuard":null,"tryCatchPattern":"if err := raftutil.MigrateToWAL(dataDir); err != nil {\n    if strings.Contains(err.Error(), \"failed to open BoltDB store\") && strings.Contains(err.Error(), \"timeout\") {\n        return fmt.Errorf(\"another process holds raft.db — stop the nomad server: %w\", err)\n    }\n    return err\n}","preventionTips":["Stop the Nomad server and wait for lock release before migrating","Confirm raft.db exists and is readable by the migration user","Never run two migrations or a migration plus server against the same data dir","Back up raft.db before starting the migration"],"tags":["boltdb","lock","migration","raft","go"],"backgroundTag":"boltdb-file-locked","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"}