hashicorp/nomad · error

deprecated config field 'RaftBoltNoFreelistSync' is set; use

Error message

deprecated config field 'RaftBoltNoFreelistSync' is set; use 'RaftLogStoreConfig.BoltDBNoFreelistSync' instead

What it means

Nomad renamed the Raft BoltDB freelist-sync option: RaftBoltNoFreelistSync was replaced by RaftLogStoreConfig.BoltDBNoFreelistSync. NewServer fails fast at startup if the deprecated field is set, refusing to start so operators don't silently rely on removed configuration.

Source

Thrown at nomad/server.go:341

	// EnterpriseState is used to fill in state for Pro/Ent builds
	EnterpriseState

	left         bool
	shutdown     bool
	shutdownLock sync.Mutex

	shutdownCtx    context.Context
	shutdownCancel context.CancelFunc
	shutdownCh     <-chan struct{}
}

// NewServer is used to construct a new Nomad server from the
// configuration, potentially returning an error
func NewServer(config *Config, consulCatalog consul.CatalogAPI, consulConfigFunc consul.ConfigAPIFunc) (*Server, error) {
	// Validate that deprecated config fields are not set
	if config.RaftBoltNoFreelistSync {
		return nil, fmt.Errorf("deprecated config field 'RaftBoltNoFreelistSync' is set; use 'RaftLogStoreConfig.BoltDBNoFreelistSync' instead")
	}

	// Configure TLS
	tlsConf, err := tlsutil.NewTLSConfiguration(config.TLSConfig, true, true)
	if err != nil {
		return nil, err
	}
	incomingTLS, tlsWrap, err := getTLSConf(config.TLSConfig.EnableRPC, tlsConf, config.Region)
	if err != nil {
		return nil, err
	}

	// Create the logger
	logger := config.Logger.ResetNamedIntercept("nomad")

	// Validate enterprise license before anything stateful happens
	if err = config.LicenseConfig.Validate(); err != nil {
		return nil, err

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove RaftBoltNoFreelistSync and set RaftLogStoreConfig.BoltDBNoFreelistSync instead (config: raft_log_store { boltdb_no_freelist_sync = true })
2. If the setting was default/no-op, delete the line entirely and restart
3. Update code that builds Config to use the new nested struct

Example fix

// before
server {
  raft_bolt_no_freelist_sync = true
}
// after
server {
  raft_log_store {
    boltdb_no_freelist_sync = true
  }
}

// Fail fast in embedders before calling NewServer
if cfg.RaftBoltNoFreelistSync {
    cfg.RaftLogStoreConfig.BoltDBNoFreelistSync = true
    cfg.RaftBoltNoFreelistSync = false
}

srv, err := nomad.NewServer(config, consulCatalog, consulConfig)
if err != nil && strings.Contains(err.Error(), "RaftBoltNoFreelistSync") {
    return fmt.Errorf("config uses deprecated RaftBoltNoFreelistSync: %w", err)
}

When it happens

Trigger: Constructing a Nomad server (NewServer) with config.RaftBoltNoFreelistSync == true — typically after populating Config from a server config file or code that still sets the old field.

Common situations: Upgrading Nomad across the version that deprecated the field while keeping an old server.hcl; in-process embedders (test harnesses, go-launchers) that set the old Config field directly; copy-pasted config from older deployments.

Related errors

• Failed to start RPC layer: %v
• Failed to start Raft: %v
• Failed to start serf: %v
• Failed to start workers: %v
• must pass non-nil job

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