{"record":{"id":"940ae26ecdf0b638","repo":"hashicorp/nomad","slug":"bind-address-resolution-failed-v","errorCode":null,"errorMessage":"Bind address resolution failed: %v","messagePattern":"Bind address resolution failed: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/config.go","lineNumber":2373,"sourceCode":"\tnc.HTTPAPIResponseHeaders = maps.Clone(c.HTTPAPIResponseHeaders)\n\tnc.Sentinel = c.Sentinel.Copy()\n\tnc.Autopilot = c.Autopilot.Copy()\n\tnc.Plugins = helper.CopySlice(c.Plugins)\n\tnc.Limits = c.Limits.Copy()\n\tnc.Audit = c.Audit.Copy()\n\tnc.Reporting = c.Reporting.Copy()\n\tnc.KEKProviders = helper.CopySlice(c.KEKProviders)\n\tnc.ExtraKeysHCL = slices.Clone(c.ExtraKeysHCL)\n\treturn &nc\n}\n\n// normalizeAddrs normalizes Addresses and AdvertiseAddrs to always be\n// initialized and have reasonable defaults.\nfunc (c *Config) normalizeAddrs() error {\n\tif c.BindAddr != \"\" {\n\t\tipStr, err := listenerutil.ParseSingleIPTemplate(c.BindAddr)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Bind address resolution failed: %v\", err)\n\t\t}\n\t\tc.BindAddr = ipStr\n\t}\n\tc.BindAddr = ipaddr.NormalizeAddr(c.BindAddr)\n\n\thttpAddrs, err := normalizeMultipleBind(c.Addresses.HTTP, c.BindAddr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to parse HTTP address: %v\", err)\n\t}\n\tc.Addresses.HTTP = strings.Join(httpAddrs, \" \")\n\n\taddr, err := normalizeBind(c.Addresses.RPC, c.BindAddr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to parse RPC address: %v\", err)\n\t}\n\tc.Addresses.RPC = addr\n\n\taddr, err = normalizeBind(c.Addresses.Serf, c.BindAddr)","sourceCodeStart":2355,"sourceCodeEnd":2391,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/config.go#L2355-L2391","documentation":"During address normalization the agent parses the configured BindAddr as a single-IP template (supporting go-sockaddr templates like {{ GetPrivateIP }}). If ParseSingleIPTemplate fails — the value is not an IP and the template does not resolve to exactly one IP — this error wraps the cause.","triggerScenarios":"Config sets bind_addr to a hostname, an invalid IP literal, or a template that evaluates to multiple/zero IPs; normalizeAddrs() runs at config parse time.","commonSituations":"Setting bind_addr = \"localhost\" or a DNS name instead of an IP; typos like \"0.0.0.0.0\"; go-sockaddr template syntax errors; using a template on a host with no matching interface.","solutions":["Set bind_addr to a literal IP (e.g. 0.0.0.0, or the host's private IP).","If using a go-sockaddr template, verify it resolves to exactly one IP and test with `nomad agent -config ... -verify-only`.","Fix typos and check the wrapped error for the parse failure detail."],"exampleFix":"# before\nbind_addr = \"my-host.example.com\"\n# after\nbind_addr = \"192.168.1.10\"        # literal IP\n# or a valid single-IP template\nbind_addr = \"{{ GetPrivateIP }}\"","handlingStrategy":"validation","validationCode":"if net.ParseIP(cfg.BindAddr) == nil && !strings.Contains(cfg.BindAddr, \"{{\") {\n  return fmt.Errorf(\"bind_addr %q must be an IP or sockaddr template\", cfg.BindAddr)\n}","typeGuard":null,"tryCatchPattern":"ipStr, err := listenerutil.ParseSingleIPTemplate(bindAddr)\nif err != nil {\n  return fmt.Errorf(\"invalid bind_addr %q: %w\", bindAddr, err)\n}","preventionTips":["Use IPs or supported go-sockaddr templates only — never hostnames","Test configs with -verify-only before rollout","Validate with net.ParseIP in config linters"],"tags":["config","network","bind-address","validation"],"backgroundTag":"invalid-bind-address","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"}