{"record":{"id":"f07acd0772afcc04","repo":"hashicorp/nomad","slug":"existing-boltdb-raft-store-found-at-s-run-nomad","errorCode":null,"errorMessage":"existing BoltDB raft store found at %s; run 'nomad operator raft migrate-backend %s' while the server is stopped to migrate to the WAL backend, then start the server again","messagePattern":"existing BoltDB raft store found at (.+?); run 'nomad operator raft migrate-backend (.+?)' while the server is stopped to migrate to the WAL backend, then start the server again","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/server.go","lineNumber":1445,"sourceCode":"\t\t\treturn err\n\t\t}\n\t\tif err := os.WriteFile(raftVersionFilePath, []byte(raftVersionFileContent), 0644); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to write Raft version file: %v\", err)\n\t\t}\n\n\t\t// Determine the raft log store backend to use.\n\t\tbackend := LogStoreBackendBoltDB\n\t\tif s.config.RaftLogStoreConfig != nil && s.config.RaftLogStoreConfig.Backend != \"\" {\n\t\t\tbackend = s.config.RaftLogStoreConfig.Backend\n\t\t}\n\n\t\tvar store raftBackend\n\t\tswitch backend {\n\t\tcase LogStoreBackendWAL:\n\t\t\t// Check for an existing BoltDB store that needs migration.\n\t\t\tboltPath := filepath.Join(path, \"raft.db\")\n\t\t\tif _, statErr := os.Stat(boltPath); statErr == nil {\n\t\t\t\treturn fmt.Errorf(\n\t\t\t\t\t\"existing BoltDB raft store found at %s; \"+\n\t\t\t\t\t\t\"run 'nomad operator raft migrate-backend %s' while the server \"+\n\t\t\t\t\t\t\"is stopped to migrate to the WAL backend, then start the server again\",\n\t\t\t\t\tboltPath, s.config.DataDir)\n\t\t\t}\n\n\t\t\twalDir := filepath.Join(path, \"wal\")\n\t\t\tif err := ensurePath(walDir, true); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to create WAL directory: %v\", err)\n\t\t\t}\n\n\t\t\twalStore, walErr := s.openRaftWAL(walDir)\n\t\t\tif walErr != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to open WAL log store: %v\", walErr)\n\t\t\t}\n\t\t\tstore = walStore\n\n\t\tcase LogStoreBackendBoltDB:","sourceCodeStart":1427,"sourceCodeEnd":1463,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L1427-L1463","documentation":"Nomad's WAL-based Raft log store backend refuses to start if a legacy BoltDB raft store (raft.db) already exists in the raft directory, because switching backends silently would lose/dupe log data. The error instructs the operator to run the offline migration command.","triggerScenarios":"setupRaft(): config selects RaftLogStoreBackend WAL (or the new default) while <raft path>/raft.db from a previous BoltDB-based server run is present.","commonSituations":"Upgrading Nomad from a version that defaulted to BoltDB to one that uses WAL; toggling raft log store config back and forth; restoring old data_dir under a new Nomad version.","solutions":["Stop the server and run `nomad operator raft migrate-backend <data_dir>` to migrate raft.db to the WAL backend, then start the server","If the old data is disposable, remove/rename <data_dir>/raft/raft.db (and understand cluster state implications — generally do not do this on a live cluster)","Keep the older Nomad version if migration is not desired"],"exampleFix":"# before: server fails to start with existing raft.db\n# after:\n$ systemctl stop nomad\n$ nomad operator raft migrate-backend /var/lib/nomad\n$ systemctl start nomad","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Join(dataDir, \"raft\", \"raft.db\")); err == nil {\n    return fmt.Errorf(\"run 'nomad operator raft migrate-backend %s' before starting WAL backend\", dataDir)\n}","typeGuard":null,"tryCatchPattern":"if err := server.Start(); err != nil {\n    if strings.Contains(err.Error(), \"existing BoltDB raft store found\") {\n        logger.Error(\"offline migration required; see error message for command\")\n    }\n    return err\n}","preventionTips":["During upgrades, read changelog notes about raft log store backend changes","Schedule a maintenance window to run migrate-backend with the server stopped","Never point a new Nomad version at an old data_dir without checking for raft.db"],"tags":["storage","raft","upgrade","nomad"],"backgroundTag":"raft-backend-migration-required","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"}