hashicorp/nomad · error

unsupported raft log store backend: %q

Error message

unsupported raft log store backend: %q

What it means

The raft log store backend is chosen from config (RaftLogStoreConfig.Backend) with a switch over known backends (WAL, BoltDB). Any other value falls to the default case and startup fails, naming the unsupported backend with %q.

Source

Thrown at nomad/server.go:1488

			boltStore, boltErr := raftboltdb.New(raftboltdb.Options{
				Path:   filepath.Join(path, "raft.db"),
				NoSync: false, // fsync each log write
				BoltOptions: &bbolt.Options{
					NoFreelistSync: noFreelistSync,
				},
				MsgpackUseNewTimeFormat: true,
			})
			if boltErr != nil {
				return boltErr
			}
			store = boltStore
			s.logger.Info("setting up raft bolt store", "no_freelist_sync", noFreelistSync)

			// Start publishing bboltdb metrics
			go boltStore.RunMetrics(s.shutdownCtx, 0)

		default:
			return fmt.Errorf("unsupported raft log store backend: %q", backend)
		}

		s.raftStore = store
		stable = store

		// If online verification of the raft log store is enabled, wire up the
		// periodic verifier. The verifier will run in the background and attempt
		// to exercise the store's verification routines (when supported) at the
		// configured interval.
		if s.config.RaftLogStoreConfig != nil && s.config.RaftLogStoreConfig.VerificationEnabled {
			// Start the verifier in background; it will stop when server shuts down.
			s.startRaftLogVerifier()
		}

		// Wrap the store in a LogCache to improve performance, unless disabled.
		disableLogCache := s.config.RaftLogStoreConfig != nil && s.config.RaftLogStoreConfig.DisableLogCache
		if disableLogCache {
			log = store

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set raft_log_store backend to a supported value: "wal" or "boltdb" (exact spelling, lowercase)
2. Check `nomad version` / docs to confirm which backends your build supports
3. Remove the backend override to use the version's default

Example fix

// before (server.hcl)
raft_log_store {
  backend = "BOLTDB"
}
// after
raft_log_store {
  backend = "boltdb"
}

var validBackends = map[string]bool{"wal": true, "boltdb": true}
b := cfg.RaftLogStoreConfig.Backend
if b != "" && !validBackends[b] {
    return fmt.Errorf("backend %q not supported; use wal or boltdb", b)
}

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "unsupported raft log store backend") {
        logger.Error("fix raft_log_store.backend in config")
    }
    return err
}

When it happens

Trigger: setupRaft(): raft_log_store { backend = "..." } in config contains a value other than "wal" or "boltdb" (case-sensitive).

Common situations: Typo in backend name ("bolt", "wal2"); wrong casing ("WAL"); copying config from another tool; newer/older Nomad version where the backend name is not recognized.

Related errors

• either ID or Address must be set
• Reschedule policy has unlimited attempts enabled and a low d
• Lock delay and TTL must be positive
• https_handshake_timeout must be >= 0
• http_max_conns_per_client must be >= 0

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