hashicorp/nomad · error

failed to write Raft version file: %v

Error message

failed to write Raft version file: %v

What it means

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.

Source

Thrown at nomad/server.go:1430

		stable = store
		log = store
		snap = raft.NewDiscardSnapshotStore()

	} else {
		// Create the base raft path
		path := filepath.Join(s.config.DataDir, raftState)
		if err := ensurePath(path, true); err != nil {
			return err
		}

		// Check Raft version and update the version file.
		raftVersionFilePath := filepath.Join(path, "version")
		raftVersionFileContent := strconv.Itoa(int(s.config.RaftConfig.ProtocolVersion))
		if err := s.checkRaftVersionFile(raftVersionFilePath); err != nil {
			return err
		}
		if err := os.WriteFile(raftVersionFilePath, []byte(raftVersionFileContent), 0644); err != nil {
			return fmt.Errorf("failed to write Raft version file: %v", err)
		}

		// Determine the raft log store backend to use.
		backend := LogStoreBackendBoltDB
		if s.config.RaftLogStoreConfig != nil && s.config.RaftLogStoreConfig.Backend != "" {
			backend = s.config.RaftLogStoreConfig.Backend
		}

		var store raftBackend
		switch backend {
		case LogStoreBackendWAL:
			// Check for an existing BoltDB store that needs migration.
			boltPath := filepath.Join(path, "raft.db")
			if _, statErr := os.Stat(boltPath); statErr == nil {
				return fmt.Errorf(
					"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",

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix ownership/permissions on data_dir (e.g. chown -R nomad:nomad /var/nomad) so the process can write
2. Free disk space or fix the underlying OS I/O error reported in %v
3. Ensure data_dir exists as a directory and is not read-only

Example fix

# before
$ nomad agent -server  # permission denied writing raft/version
# after
$ sudo chown -R nomad:nomad /var/lib/nomad
$ nomad agent -server

vf := filepath.Join(dataDir, "raft", "version")
if err := os.WriteFile(vf, []byte("probe"), 0644); err != nil {
    return fmt.Errorf("data dir not writable: %w", err)
}
os.Remove(vf)

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "failed to write Raft version file") {
        logger.Error("check data_dir permissions and disk space")
    }
    return err
}

When it happens

Trigger: setupRaft(): os.WriteFile(raftVersionFilePath, ...) returns a non-nil error while writing the protocol version string to <raft path>/version.

Common situations: 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.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

• failed to create WAL directory: %v
• failed to write peers.info file: %v
• plugin not found
• plugin not executable
• CSI.ControllerAttachVolume: VolumeID is required

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/97ea5318e2712242. Report an issue: GitHub.