{"record":{"id":"c6f6bd6693afc196","repo":"hashicorp/nomad","slug":"failed-to-initialize-consul-client-v-c6f6bd","errorCode":null,"errorMessage":"Failed to initialize Consul client: %v","messagePattern":"Failed to initialize Consul client: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"command/agent/agent.go","lineNumber":166,"sourceCode":"\n// NewAgent is used to create a new agent with the given configuration\nfunc NewAgent(config *Config, logger log.InterceptLogger, logOutput io.Writer, inmem *metrics.InmemSink) (*Agent, error) {\n\ta := &Agent{\n\t\tconfig:     config,\n\t\tlogOutput:  logOutput,\n\t\tshutdownCh: make(chan struct{}),\n\t\tinmemSink:  inmem,\n\t}\n\n\t// Create the loggers\n\ta.logger = logger\n\ta.httpLogger = a.logger.ResetNamed(\"http\")\n\n\t// Global logger should match internal logger as much as possible\n\tgolog.SetFlags(golog.LstdFlags | golog.Lmicroseconds)\n\n\tif err := a.setupConsuls(config.Consuls); err != nil {\n\t\treturn nil, fmt.Errorf(\"Failed to initialize Consul client: %v\", err)\n\t}\n\n\tif err := a.setupServer(); err != nil {\n\t\treturn nil, err\n\t}\n\tif err := a.setupClient(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err := a.setupEnterpriseAgent(logger); err != nil {\n\t\treturn nil, err\n\t}\n\tif a.client == nil && a.server == nil {\n\t\treturn nil, fmt.Errorf(\"must have at least client or server mode enabled\")\n\t}\n\n\t// If the agent is configured with TLS, set up the TLS metrics process to\n\t// emit certificate expiry metrics and start this.","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L148-L184","documentation":"NewAgent wraps any error from setupConsuls (building the agent's Consul client wrappers from config.Consuls) with 'Failed to initialize Consul client: %v'. Agent startup aborts because Nomad cannot talk to Consul for service discovery/health checks.","triggerScenarios":"setupConsuls fails for any configured Consul cluster — invalid Consul config block (bad address, TLS/ACL settings), unreachable Consul agent, or API client construction errors (api.NewClient / NewNamespacedClient).","commonSituations":"Wrong consul.address in Nomad config; Consul not running or on a different port; ACL token invalid; TLS CA/cert misconfiguration; multiple Consul clusters (Consuls) with one bad entry; DNS resolution failure for the Consul hostname.","solutions":["Read the wrapped %v cause and validate the consul stanza (address, port, scheme, tls, token).","Confirm the Consul agent is reachable: curl the configured address (e.g. http://127.0.0.1:8500/v1/status/leader).","Fix TLS/ACL settings — verify ca_file/cert_file/key_file paths and the acl token.","Test config with 'nomad agent -config ... ' in dev mode or 'consul agent -dev' locally to isolate.","Remove or correct the offending entry if multiple Consuls are configured."],"exampleFix":"// before\nconsul {\n  address = \"consul.internal:8500\"  # DNS unresolvable on this host\n}\n// after\nconsul {\n  address = \"127.0.0.1:8500\"\n  token   = \"<valid-acl-token>\"\n}","handlingStrategy":"validation","validationCode":"// pre-flight check before starting the agent\naddr := cfg.Consuls[0].Addr // consul address from config\nresp, err := http.Get(addr + \"/v1/status/leader\")\nif err != nil || resp.StatusCode != 200 {\n    return fmt.Errorf(\"consul unreachable at %s\", addr)\n}","typeGuard":null,"tryCatchPattern":"agent, err := NewAgent(config, logger)\nif err != nil {\n    if strings.Contains(err.Error(), \"Failed to initialize Consul client\") {\n        logger.Error(\"consul init failed\", \"cause\", err)\n        // validate consul stanza, reachability, TLS and ACL token\n    }\n    return err\n}","preventionTips":["Validate the consul stanza with 'nomad agent -verify-config' or 'nomad config validate'","Health-check Consul from the host before launching Nomad","Keep CA/cert/key paths and ACL tokens current","Test multi-cluster Consul configs individually"],"tags":["consul","startup","config","nomad"],"backgroundTag":"consul-client-init-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"}