{"record":{"id":"283e45fb922515dd","repo":"hashicorp/nomad","slug":"unable-to-parse-default-advertise-address-v","errorCode":null,"errorMessage":"Unable to parse default advertise address: %v","messagePattern":"Unable to parse default advertise address: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/config.go","lineNumber":2573,"sourceCode":"\n\t// Return the first non-localhost unicast address\n\tfor _, ip := range ips {\n\t\tif ip.IsLinkLocalUnicast() || ip.IsGlobalUnicast() {\n\t\t\treturn normalizeAddrWithPort(ip.String(), defport), nil\n\t\t}\n\t\tif ip.IsLoopback() {\n\t\t\tif dev {\n\t\t\t\t// loopback is fine for dev mode\n\t\t\t\treturn normalizeAddrWithPort(ip.String(), defport), nil\n\t\t\t}\n\t\t\treturn \"\", fmt.Errorf(\"Defaulting advertise to localhost is unsafe, please set advertise manually\")\n\t\t}\n\t}\n\n\t// Bind is not localhost but not a valid advertise IP, use first private IP\n\taddr, err = listenerutil.ParseSingleIPTemplate(\"{{ GetPrivateIP }}\")\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"Unable to parse default advertise address: %v\", err)\n\t}\n\treturn normalizeAddrWithPort(addr, defport), nil\n}\n\n// isMissingPort returns true if an error is a \"missing port\" error from\n// net.SplitHostPort.\nfunc isMissingPort(err error) bool {\n\t// matches error const in net/ipsock.go\n\tconst missingPort = \"missing port in address\"\n\treturn err != nil && strings.Contains(err.Error(), missingPort)\n}\n\n// isTooManyColons returns true if an error is a \"too many colons\" error from\n// net.SplitHostPort.\nfunc isTooManyColons(err error) bool {\n\t// matches error const in net/ipsock.go\n\tconst tooManyColons = \"too many colons in address\"\n\treturn err != nil && strings.Contains(err.Error(), tooManyColons)","sourceCodeStart":2555,"sourceCodeEnd":2591,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/config.go#L2555-L2591","documentation":"As a last resort normalizeAdvertise() evaluates the built-in template {{ GetPrivateIP }} to pick the first private IP. This error wraps failure of that template evaluation, meaning Consul could not determine any usable private advertise address.","triggerScenarios":"advertise unset, bind fallback failed or yielded no acceptable IP, and ParseSingleIPTemplate(\"{{ GetPrivateIP }}\") errors — typically when the host has no private (RFC1918/global unicast, non-loopback) address.","commonSituations":"Loopback-only containers or minimal VMs without configured networking, unusual network setups where GetPrivateIP finds no candidate interface, running Consul on hosts with only link-local addresses.","solutions":["Set advertise_addr explicitly to a valid routable IP — this bypasses the default entirely","Configure a non-loopback interface with a private IP on the host","Check network interface configuration (ip addr / ifconfig) before starting Consul","If no private IP is appropriate, advertise a public IP deliberately"],"exampleFix":"// before\n// no advertise set on loopback-only host\n// after\nadvertise_addr = \"203.0.113.10\"","handlingStrategy":"fallback","validationCode":"ip, ok := firstPrivateIP()\nif !ok {\n    return errors.New(\"host has no private IP; configure advertise_addr manually\")\n}","typeGuard":null,"tryCatchPattern":"if err := startAgent(); err != nil && strings.Contains(err.Error(), \"default advertise\") {\n    ip := promptOrConfiguredIP()\n    return startAgentWithAdvertise(net.JoinHostPort(ip, \"8301\"))\n}","preventionTips":["Always set advertise_addr in provisioning templates","Check interface configuration (ip addr) in CI/health checks","For multi-homed hosts, pin advertise to a specific interface IP","Document that {{ GetPrivateIP }} requires a private interface"],"tags":["network","config","consul","advertise-address","private-ip"],"backgroundTag":"no-routable-ip-found","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"}