{"record":{"id":"f72d9ad8d5b0804c","repo":"hashicorp/nomad","slug":"server-config-setup-failed-s","errorCode":null,"errorMessage":"server config setup failed: %s","messagePattern":"server config setup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"command/agent/agent.go","lineNumber":1184,"sourceCode":"\t\tconf.Fingerprinters[fingerprinterCfg.Name] = fingerprinterCfg\n\t}\n\n\tconf.LogFile = agentConfig.LogFile\n\tconf.DefaultIneligible = agentConfig.Client.DefaultIneligible\n\n\treturn conf, nil\n}\n\n// setupServer is used to setup the server if enabled\nfunc (a *Agent) setupServer() error {\n\tif !a.config.Server.Enabled {\n\t\treturn nil\n\t}\n\n\t// Setup the configuration\n\tconf, err := a.serverConfig()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"server config setup failed: %s\", err)\n\t}\n\n\t// Generate a node ID and persist it if it is the first instance, otherwise\n\t// read the persisted node ID.\n\tif err := a.setupNodeID(conf); err != nil {\n\t\treturn fmt.Errorf(\"setting up server node ID failed: %s\", err)\n\t}\n\n\t// Sets up the keyring for gossip encryption\n\tif err := a.setupKeyrings(conf); err != nil {\n\t\treturn fmt.Errorf(\"failed to configure keyring: %v\", err)\n\t}\n\n\t// Create the server\n\tserver, err := nomad.NewServer(conf,\n\t\ta.consulCatalog,           // self service discovery\n\t\ta.consulConfigEntriesFunc, // writing config entries for gateways\n\t)","sourceCodeStart":1166,"sourceCodeEnd":1202,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L1166-L1202","documentation":"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.).","triggerScenarios":"Any error returned from serverConfig during agent startup: bad data_dir permissions/paths, invalid server block values, TLS config problems — called only from NewAgent.","commonSituations":"Unwritable or missing data_dir, invalid server { ... } stanza values, misconfigured TLS certificate/key paths, or conflicting server settings in the HCL/JSON config.","solutions":["Read the wrapped %s detail to find the underlying config problem","Check data_dir exists and the Nomad user has read/write permissions","Validate TLS cert/key/CA paths if tls is configured","Run `nomad agent -verify-only` to validate config without starting"],"exampleFix":"// before\nserver { enabled = true }\ndata_dir = \"/nonexistent/dir\"\n// after\nserver { enabled = true }\ndata_dir = \"/opt/nomad/data\"  # must exist and be writable","handlingStrategy":"try-catch","validationCode":"// Check data_dir is writable before starting\nif err := os.MkdirAll(dataDir+\"/server\", 0700); err != nil {\n    log.Fatalf(\"data_dir not usable: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"conf, err := setupServer()\nif err != nil {\n    var cfgErr *ConfigError\n    if errors.As(err, &cfgErr) {\n        log.Fatalf(\"fix agent config: %v\", err)\n    }\n    return fmt.Errorf(\"server config setup failed: %s\", err)\n}","preventionTips":["Ensure data_dir exists and is writable by the Nomad user before launch","Validate config with `nomad agent -verify-only` in CI/deploy scripts","Keep TLS cert/key paths absolute and verified in config management","Log the wrapped underlying error, not just the wrapper"],"tags":["nomad","server","config-setup","startup"],"backgroundTag":"server-config-setup-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}