{"record":{"id":"faa01970df6d278d","repo":"hashicorp/nomad","slug":"failed-to-open-raft-logs-v","errorCode":null,"errorMessage":"failed to open raft logs: %v","messagePattern":"failed to open raft logs: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/state.go","lineNumber":64,"sourceCode":"\t}\n\treturn raftStateInfoBoltDB(p)\n}\n\nfunc raftStateInfoBoltDB(p string) (store RaftStore, firstIdx uint64, lastIdx uint64, err error) {\n\topts := raftboltdb.Options{\n\t\tPath: p,\n\t\tBoltOptions: &bbolt.Options{\n\t\t\tReadOnly: true,\n\t\t\tTimeout:  1 * time.Second,\n\t\t},\n\t\tMsgpackUseNewTimeFormat: true,\n\t}\n\ts, err := raftboltdb.New(opts)\n\tif err != nil {\n\t\tif strings.HasSuffix(err.Error(), \"timeout\") {\n\t\t\treturn nil, 0, 0, errAlreadyOpen\n\t\t}\n\t\treturn nil, 0, 0, fmt.Errorf(\"failed to open raft logs: %v\", err)\n\t}\n\n\tfirstIdx, err = s.FirstIndex()\n\tif err != nil {\n\t\treturn nil, 0, 0, fmt.Errorf(\"failed to fetch first index: %v\", err)\n\t}\n\n\tlastIdx, err = s.LastIndex()\n\tif err != nil {\n\t\treturn nil, 0, 0, fmt.Errorf(\"failed to fetch last index: %v\", err)\n\t}\n\n\treturn s, firstIdx, lastIdx, nil\n}\n\nfunc raftStateInfoWAL(p string) (store RaftStore, firstIdx uint64, lastIdx uint64, err error) {\n\ts, err := raftwal.Open(p)\n\tif err != nil {","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/state.go#L46-L82","documentation":"raftStateInfoBoltDB opens the BoltDB-backed Raft log via raftboltdb.New(opts). This error wraps any open failure except the special 'timeout' case (mapped to errAlreadyOpen). Typical causes are file corruption, wrong file type, or I/O problems — i.e., the file exists but could not be opened as a Raft BoltDB store.","triggerScenarios":"raftboltdb.New failing on the given raft.db path: file is not a BoltDB database, BoltDB freelist/meta corruption, snapshot-in-progress or lock-file contention (non-timeout errors), or read-only filesystem. Note: 'timeout' suffix errors are reported as errAlreadyOpen instead of this message.","commonSituations":"Pointing the tool at a WAL file or an unrelated file named raft.db, inspecting raft.db from a node that crashed mid-write, copying raft.db while Consul was running (torn copy), or a filesystem mounted read-only.","solutions":["Confirm the file is the BoltDB raft.db (first bytes are BoltDB magic 0xED0CDAED), not a WAL file or another DB.","Stop Consul or copy the file cleanly (consul snapshot backup or filesystem-consistent copy) and inspect the copy instead of a live/torn one.","If corruption is indicated, restore raft state from a verified snapshot rather than trying to open the damaged DB.","Check filesystem mounts and permissions; ensure the path is writable if the tool opens read-write.","If you actually hit a lock 'timeout' error, a store is already open — that surfaces as errAlreadyOpen, not this message."],"exampleFix":"// before\nstore, _, _, err := raftutil.RaftStateInfo(\"/var/lib/consul/raft/raft.db\") // live, torn copy\n\n// after\n// stop the agent or take a consistent copy first\ncmd := exec.Command(\"cp\", \"--reflink=auto\", raftDB, workCopy)\nif err := cmd.Run(); err != nil {\n    log.Fatal(err)\n}\nstore, _, _, err := raftutil.RaftStateInfo(workCopy)","handlingStrategy":"validation","validationCode":"func isBoltDBFile(p string) (bool, error) {\n    f, err := os.Open(p)\n    if err != nil {\n        return false, err\n    }\n    defer f.Close()\n    magic := make([]byte, 4)\n    if _, err := io.ReadFull(f, magic); err != nil {\n        return false, err\n    }\n    return bytes.Equal(magic, []byte{0xED, 0x0C, 0xDA, 0xED}), nil\n}","typeGuard":null,"tryCatchPattern":"store, _, _, err := raftutil.RaftStateInfo(raftDB)\nif err != nil {\n    if errors.Is(err, raftutil.ErrAlreadyOpen) {\n        log.Printf(\"store already open elsewhere\")\n    } else if strings.Contains(err.Error(), \"failed to open raft logs\") {\n        log.Printf(\"raft.db corrupt or wrong file type: %v\", err)\n    }\n}","preventionTips":["Verify BoltDB magic bytes before opening.","Never inspect a live raft.db; stop the agent or take a filesystem-consistent copy.","Watch for errAlreadyOpen: a 'timeout' error means another process holds the BoltDB file lock.","Ensure the filesystem is mounted read-write."],"tags":["raft","boltdb","corruption","go"],"backgroundTag":"bolt-db-open-failed","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"}