{"record":{"id":"97ea5318e2712242","repo":"hashicorp/nomad","slug":"failed-to-write-raft-version-file-v","errorCode":null,"errorMessage":"failed to write Raft version file: %v","messagePattern":"failed to write Raft version file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/server.go","lineNumber":1430,"sourceCode":"\t\tstable = store\n\t\tlog = store\n\t\tsnap = raft.NewDiscardSnapshotStore()\n\n\t} else {\n\t\t// Create the base raft path\n\t\tpath := filepath.Join(s.config.DataDir, raftState)\n\t\tif err := ensurePath(path, true); err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\t// Check Raft version and update the version file.\n\t\traftVersionFilePath := filepath.Join(path, \"version\")\n\t\traftVersionFileContent := strconv.Itoa(int(s.config.RaftConfig.ProtocolVersion))\n\t\tif err := s.checkRaftVersionFile(raftVersionFilePath); err != nil {\n\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\",","sourceCodeStart":1412,"sourceCodeEnd":1448,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L1412-L1448","documentation":"During raft setup, Nomad persists the configured Raft protocol version into <data_dir>/raft/version and compares it against any existing file via checkRaftVersionFile. If os.WriteFile fails (permissions, disk full, path issues), the error is wrapped with this message.","triggerScenarios":"setupRaft(): os.WriteFile(raftVersionFilePath, ...) returns a non-nil error while writing the protocol version string to <raft path>/version.","commonSituations":"data_dir owned by another user (ran nomad as root once, then as unprivileged user); read-only filesystem/container; disk full; data_dir path is a file, not a directory.","solutions":["Fix ownership/permissions on data_dir (e.g. chown -R nomad:nomad /var/nomad) so the process can write","Free disk space or fix the underlying OS I/O error reported in %v","Ensure data_dir exists as a directory and is not read-only"],"exampleFix":"# before\n$ nomad agent -server  # permission denied writing raft/version\n# after\n$ sudo chown -R nomad:nomad /var/lib/nomad\n$ nomad agent -server","handlingStrategy":"validation","validationCode":"vf := filepath.Join(dataDir, \"raft\", \"version\")\nif err := os.WriteFile(vf, []byte(\"probe\"), 0644); err != nil {\n    return fmt.Errorf(\"data dir not writable: %w\", err)\n}\nos.Remove(vf)","typeGuard":null,"tryCatchPattern":"if err := server.Start(); err != nil {\n    if strings.Contains(err.Error(), \"failed to write Raft version file\") {\n        logger.Error(\"check data_dir permissions and disk space\")\n    }\n    return err\n}","preventionTips":["Run the agent as a consistent user with write access to data_dir","Monitor disk space on the data_dir volume","Smoke-test data_dir writability in startup/health scripts"],"tags":["filesystem","storage","nomad"],"backgroundTag":"file-write-permission-denied","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"}