hashicorp/nomad · error

failed to write peers.info file: %v

Error message

failed to write peers.info file: %v

What it means

During Raft store initialization the server could not write the peers.info sentinel file under the data directory; this wraps the filesystem error, typically caused by permissions, a full disk, or an invalid path.

Source

Thrown at nomad/server.go:1537

			if s.raftStore != nil {
				s.raftStore.Close()
			}
			return err
		}
		snap = snapshots

		// For an existing cluster being upgraded to the new version of
		// Raft, we almost never want to run recovery based on the old
		// peers.json file. We create a peers.info file with a helpful
		// note about where peers.json went, and use that as a sentinel
		// to avoid ingesting the old one that first time (if we have to
		// create the peers.info file because it's not there, we also
		// blow away any existing peers.json file).
		peersFile := filepath.Join(path, "peers.json")
		peersInfoFile := filepath.Join(path, "peers.info")
		if _, err := os.Stat(peersInfoFile); os.IsNotExist(err) {
			if err := os.WriteFile(peersInfoFile, []byte(peersInfoContent), 0644); err != nil {
				return fmt.Errorf("failed to write peers.info file: %v", err)
			}

			// Blow away the peers.json file if present, since the
			// peers.info sentinel wasn't there.
			if _, err := os.Stat(peersFile); err == nil {
				if err := os.Remove(peersFile); err != nil {
					return fmt.Errorf("failed to delete peers.json, please delete manually (see peers.info for details): %v", err)
				}
				s.logger.Info("deleted peers.json file (see peers.info for details)")
			}
		} else if _, err := os.Stat(peersFile); err == nil {
			s.logger.Info("found peers.json file, recovering Raft configuration...")
			var configuration raft.Configuration
			if s.config.RaftConfig.ProtocolVersion < 3 {
				configuration, err = raft.ReadPeersJSON(peersFile)
			} else {
				configuration, err = raft.ReadConfigJSON(peersFile)
			}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check data_dir exists and is writable by the Nomad user
2. Free disk space or fix the filesystem error reported by the OS
3. Retry starting the server once the underlying IO problem is resolved

Example fix

# before: read-only raft dir
# after
$ sudo chown -R nomad:nomad /var/lib/nomad/raft
$ sudo systemctl restart nomad

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

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "failed to write peers.info file") {
        logger.Error("check raft dir permissions/disk space")
    }
    return err
}

When it happens

Trigger: setupRaft(): peers.info does not exist and os.WriteFile(peersInfoFile, peersInfoContent, 0644) fails while initializing <data_dir>/raft.

Common situations: data_dir permissions wrong; read-only filesystem; disk full; data_dir path misconfigured to a non-writable location.

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 find raft store in %v: %v
• no raft store (raft.db or wal/) found in %s
• failed to write Raft version file: %v
• existing BoltDB raft store found at %s; run 'nomad operator

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