{"record":{"id":"a0e6394abda16b10","repo":"hashicorp/nomad","slug":"invalid-port-q-port-label-not-found-or-is-not-nu","errorCode":null,"errorMessage":"invalid port %q: port label not found or is not numeric","messagePattern":"invalid port %q: port label not found or is not numeric","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/serviceregistration/address.go","lineNumber":167,"sourceCode":"\t\tif portLabel == \"\" {\n\t\t\treturn getAddressPort(addressMode, netStatus, 0)\n\t\t}\n\n\t\t// If port is a label and is found then return it\n\t\tif port, ok := ports.Get(portLabel); ok {\n\t\t\t// Use port.To value unless not set\n\t\t\tif port.To > 0 {\n\t\t\t\treturn getAddressPort(addressMode, netStatus, port.To)\n\t\t\t}\n\n\t\t\treturn getAddressPort(addressMode, netStatus, port.Value)\n\t\t}\n\n\t\t// Check if port is a literal number\n\t\tport, err := strconv.Atoi(portLabel)\n\t\tif err != nil {\n\t\t\t// User likely specified wrong port label here\n\t\t\treturn \"\", 0, fmt.Errorf(\"invalid port %q: port label not found or is not numeric\", portLabel)\n\t\t}\n\t\tif port <= 0 {\n\t\t\treturn \"\", 0, fmt.Errorf(\"invalid port: %q: port must be >0\", portLabel)\n\t\t}\n\n\t\treturn getAddressPort(addressMode, netStatus, port)\n\tdefault:\n\t\t// Shouldn't happen due to validation, but enforce invariants\n\t\treturn \"\", 0, fmt.Errorf(\"invalid address mode %q\", addressMode)\n\t}\n}\n\n// getAddressPort is a helper function to return the IPv6 or IPv4 address based on the addressMode\nfunc getAddressPort(addressMode string, netStatus *structs.AllocNetworkStatus, port int) (string, int, error) {\n\tif addressMode == structs.AddressModeAllocIPv6 {\n\t\treturn netStatus.AddressIPv6, port, nil\n\t}\n","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/serviceregistration/address.go#L149-L185","documentation":"GetAddress resolves a service's port label to an advertised port. If the port label is not found in the task's/network's port map AND it is not itself a literal number (strconv.Atoi fails), this error is returned. It signals a misconfiguration in the service or check stanza's port field.","triggerScenarios":"service { port = \"foo\" } where \"foo\" is neither a declared port label in the task's port block nor the group network's port block, nor a numeric literal like \"8080\". Raised via serviceRegs/generateNomadServiceRegistration when resolving service or check addresses.","commonSituations":"Typo in port label (e.g. \"htpp\" vs \"http\"); referencing a port label defined in a different task; using a label that exists only in a task network when the service is group-level (or vice versa); forgetting to declare a dynamic port before referencing it.","solutions":["Fix the port label to match a declared port in the task or group network stanza","Use a numeric literal port (e.g. port = 8080) if advertising a fixed port","Declare the missing port block with the label in the task group network section","Check task vs group level: group-level services can only reference group network port labels"],"exampleFix":"// before\nservice {\n  name = \"web\"\n  port = \"htpp\"\n}\n// after\nservice {\n  name = \"web\"\n  port = \"http\"\n}","handlingStrategy":"validation","validationCode":"labels := collectPortLabels(task, group) // union of task + group network port labels\nif !isNumericLiteral(service.PortLabel) && !labels[service.PortLabel] {\n    return fmt.Errorf(\"service %q: port label %q not declared\", service.Name, service.PortLabel)\n}","typeGuard":null,"tryCatchPattern":"ip, port, err := GetAddress(addr, mode, portLabel, networks, dn, ports, netStatus)\nif err != nil && strings.Contains(err.Error(), \"port label not found\") {\n    logger.Error(\"service port label misconfigured\", \"service\", name, \"label\", portLabel, \"err\", err)\n    return err\n}","preventionTips":["Keep a canonical list of declared port labels and lint job specs against it","Use dynamic port labels instead of hardcoding names in services","Check task-level vs group-level scope: group services reference group network ports only","Run nomad job validate in CI before every submit"],"tags":["nomad","service-registration","port-label","configuration"],"backgroundTag":"port-label-not-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"}