{"record":{"id":"326f6234a5f9c3d3","repo":"hashicorp/nomad","slug":"failed-to-parse-serf-advertise-address-v","errorCode":null,"errorMessage":"Failed to parse Serf advertise address: %v","messagePattern":"Failed to parse Serf advertise address: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/config.go","lineNumber":2422,"sourceCode":"\t}\n\n\taddr, err = normalizeAdvertise(c.AdvertiseAddrs.HTTP, httpAddrs[0], c.Ports.HTTP, c.DevMode)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to parse HTTP advertise address (%v, %v, %v, %v): %v\", c.AdvertiseAddrs.HTTP, c.Addresses.HTTP, c.Ports.HTTP, c.DevMode, err)\n\t}\n\tc.AdvertiseAddrs.HTTP = addr\n\n\taddr, err = normalizeAdvertise(c.AdvertiseAddrs.RPC, c.Addresses.RPC, c.Ports.RPC, c.DevMode)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"Failed to parse RPC advertise address: %v\", err)\n\t}\n\tc.AdvertiseAddrs.RPC = addr\n\n\t// Skip serf if server is disabled\n\tif c.Server != nil && c.Server.Enabled {\n\t\taddr, err = normalizeAdvertise(c.AdvertiseAddrs.Serf, c.Addresses.Serf, c.Ports.Serf, c.DevMode)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to parse Serf advertise address: %v\", err)\n\t\t}\n\t\tc.AdvertiseAddrs.Serf = addr\n\t}\n\n\t// Skip network_interface evaluation if not a client\n\tif c.Client != nil && c.Client.Enabled && c.Client.NetworkInterface != \"\" {\n\t\tparsed, err := parseSingleInterfaceTemplate(c.Client.NetworkInterface)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to parse network-interface: %v\", err)\n\t\t}\n\n\t\tc.Client.NetworkInterface = parsed\n\t}\n\n\treturn nil\n}\n\n// parseSingleInterfaceTemplate parses a go-sockaddr template and returns an","sourceCodeStart":2404,"sourceCodeEnd":2440,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/config.go#L2404-L2440","documentation":"For server agents, AdvertiseAddrs.Serf is validated with normalizeAdvertise using the Serf bind address and Ports.Serf (skipped when server is disabled). Failure to parse or validate the Serf advertise address aborts startup with this error, wrapping the underlying cause.","triggerScenarios":"advertise_addrs.serf set to an unresolvable host, invalid IP/port, or an address that normalizeAdvertise cannot merge with Ports.Serf; only evaluated when server.enabled = true.","commonSituations":"Advertise name resolving only via a DNS entry missing on the node; wrong interface IP after cloud instance restart; typos like 'serf:8301' where a host was expected.","solutions":["Set advertise_addrs.serf to a valid host:port on this node","Verify the hostname resolves locally and the IP is assigned to the node","Use the bind-derived default by removing the override if unsure","Check wrapped %v detail for the exact parse error"],"exampleFix":"// before\nadvertise_addrs { serf = \"node-cluster-internal:8301\" } # name unresolvable\n// after\nadvertise_addrs { serf = \"10.0.0.5:8301\" }","handlingStrategy":"validation","validationCode":"if serverEnabled {\n\thost, port, err := net.SplitHostPort(cfg.AdvertiseAddrs.Serf)\n\tif err == nil {\n\t\tif net.ParseIP(host) == nil { _, _ = net.LookupHost(host) }\n\t\t_, _ = strconv.Atoi(port)\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set advertise_addrs.serf when server.enabled is true","Validate hostname resolution locally before deploy","Use the bind-derived default if unsure"],"tags":["config","network","advertise-address","serf"],"backgroundTag":"invalid-advertise-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"}