{"record":{"id":"0d73e196a2d6cf61","repo":"hashicorp/nomad","slug":"client-setup-failed-v","errorCode":null,"errorMessage":"client setup failed: %v","messagePattern":"client setup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"command/agent/agent.go","lineNumber":1372,"sourceCode":"}\n\n// setupClient is used to setup the client if enabled\nfunc (a *Agent) setupClient() error {\n\tif !a.config.Client.Enabled {\n\t\treturn nil\n\t}\n\n\t// Plugin setup must happen before the call to clientConfig, because it\n\t// copies the pointers to the plugin loaders from the Agent to the\n\t// Client config.\n\tif err := a.setupPlugins(); err != nil {\n\t\treturn err\n\t}\n\n\t// Setup the configuration\n\tconf, err := a.clientConfig()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"client setup failed: %v\", err)\n\t}\n\n\t// Reserve some ports for the plugins if we are on Windows\n\tif runtime.GOOS == \"windows\" {\n\t\tif err := a.reservePortsForClient(conf); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\tif conf.StateDBFactory == nil {\n\t\tconf.StateDBFactory = state.GetStateDBFactory(conf.DevMode)\n\t}\n\n\t// Set up a custom listener and dialer. This is used by Nomad clients when\n\t// running consul-template functions that utilize the Nomad API. We lazy\n\t// load this into the client config, therefore this needs to happen before\n\t// we call NewClient.\n\ta.builtinListener, a.builtinDialer = bufconndialer.New()\n\tconf.TemplateDialer = a.builtinDialer","sourceCodeStart":1354,"sourceCodeEnd":1390,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L1354-L1390","documentation":"This error wraps any failure that occurs while building the Nomad client configuration during agent startup (a.clientConfig() in setupClient). setupClient is called by NewAgent, so any malformed client config stanza, unparsable field, or invalid option aborts agent bring-up. The wrapped error carries the underlying cause; this message only marks the phase.","triggerScenarios":"Calling NewAgent (e.g. `nomad agent -client`) where a.clientConfig() returns an error: invalid or unparsable [client] config block, bad datacenter/name values, invalid client options (e.g. bad max_kill_timeout, unknown option keys), or bad addresses/interfaces in the config.","commonSituations":"Typo or invalid type in the client stanza of an HCL/JSON config file; environment-derived config overrides producing invalid values; upgrading Nomad after a client option was removed or renamed so the old config no longer validates.","solutions":["Read the wrapped '%v' detail in the log — it names the exact config field that failed","Fix the offending entry in the [client] section of the agent config file (or the -client-* CLI flags)","Run `nomad agent -config ... -verify-only` or `nomad config validate` to check the config before starting","Upgrade/downgrade Nomad so config keys match the running binary version"],"exampleFix":"// before (invalid client option)\nclient {\n  option = \"bogus-value\"\n}\n// after\nclient {\n  enabled = true\n  servers = [\"127.0.0.1:4647\"]\n}","handlingStrategy":"validation","validationCode":"if err := exec.Command(\"nomad\", \"config\", \"validate\", cfgPath).Run(); err != nil {\n    return fmt.Errorf(\"invalid agent config %s: %w\", cfgPath, err)\n}","typeGuard":null,"tryCatchPattern":"if err := NewAgent(...); err != nil {\n    var cfgErr *ConfigParseError\n    if strings.Contains(err.Error(), \"client setup failed\") {\n        log.Fatalf(\"fix [client] config: %v\", err)\n    }\n    return err\n}","preventionTips":["Run `nomad config validate` in CI before deploys","Pin client config keys to the Nomad version's documented schema","Test agent startup with -verify-only in staging"],"tags":["nomad","configuration","startup","agent"],"backgroundTag":"invalid-configuration","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"}