hashicorp/nomad · critical

server config setup failed: %s

Error message

server config setup failed: %s

What it means

setupServer builds the server configuration via a.serverConfig(); if that fails, the error is wrapped as 'server config setup failed' and NewAgent aborts. It indicates the server-side configuration could not be assembled (paths, TLS, raft/serf settings, etc.).

Source

Thrown at command/agent/agent.go:1184

		conf.Fingerprinters[fingerprinterCfg.Name] = fingerprinterCfg
	}

	conf.LogFile = agentConfig.LogFile
	conf.DefaultIneligible = agentConfig.Client.DefaultIneligible

	return conf, nil
}

// setupServer is used to setup the server if enabled
func (a *Agent) setupServer() error {
	if !a.config.Server.Enabled {
		return nil
	}

	// Setup the configuration
	conf, err := a.serverConfig()
	if err != nil {
		return fmt.Errorf("server config setup failed: %s", err)
	}

	// Generate a node ID and persist it if it is the first instance, otherwise
	// read the persisted node ID.
	if err := a.setupNodeID(conf); err != nil {
		return fmt.Errorf("setting up server node ID failed: %s", err)
	}

	// Sets up the keyring for gossip encryption
	if err := a.setupKeyrings(conf); err != nil {
		return fmt.Errorf("failed to configure keyring: %v", err)
	}

	// Create the server
	server, err := nomad.NewServer(conf,
		a.consulCatalog,           // self service discovery
		a.consulConfigEntriesFunc, // writing config entries for gateways
	)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped %s detail to find the underlying config problem
2. Check data_dir exists and the Nomad user has read/write permissions
3. Validate TLS cert/key/CA paths if tls is configured
4. Run `nomad agent -verify-only` to validate config without starting

Example fix

// before
server { enabled = true }
data_dir = "/nonexistent/dir"
// after
server { enabled = true }
data_dir = "/opt/nomad/data"  # must exist and be writable

// Check data_dir is writable before starting
if err := os.MkdirAll(dataDir+"/server", 0700); err != nil {
    log.Fatalf("data_dir not usable: %v", err)
}

conf, err := setupServer()
if err != nil {
    var cfgErr *ConfigError
    if errors.As(err, &cfgErr) {
        log.Fatalf("fix agent config: %v", err)
    }
    return fmt.Errorf("server config setup failed: %s", err)
}

When it happens

Trigger: Any error returned from serverConfig during agent startup: bad data_dir permissions/paths, invalid server block values, TLS config problems — called only from NewAgent.

Common situations: Unwritable or missing data_dir, invalid server { ... } stanza values, misconfigured TLS certificate/key paths, or conflicting server settings in the HCL/JSON config.

Related errors

• server setup failed: %v
• failed to fetch signed identities: %w
• Failed to initialize Consul client: %v
• must have at least client or server mode enabled
• failed to set up TLS expiration metrics: %w

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