deprecated config field 'RaftBoltNoFreelistSync' is set…

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.

Solutions

Remove RaftBoltNoFreelistSync and set RaftLogStoreConfig.BoltDBNoFreelistSync instead (config: raft_log_store { boltdb_no_freelist_sync = true })
If the setting was default/no-op, delete the line entirely and restart
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
  }
}

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Grep configs for raft_bolt_no_freelist_sync before upgrades and migrate to raft_log_store block
Treat NewServer startup errors as fatal config validation in deployment scripts
Pin config schema docs to the Nomad version being deployed

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

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

Appendix: 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)