{"record":{"id":"880746a06f2cea7a","repo":"hashicorp/nomad","slug":"consul-connect-transparent-proxy-port-q-must-be-n","errorCode":null,"errorMessage":"Consul Connect transparent proxy port %q must be numeric or one of network.port labels","messagePattern":"Consul Connect transparent proxy port %q must be numeric or one of network\\.port labels","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/job_endpoint_hook_connect.go","lineNumber":605,"sourceCode":"\t\t\t\t\treturn fmt.Errorf(\n\t\t\t\t\t\t\"Consul Connect services %q and %q in group %q using same address for upstreams (%s)\",\n\t\t\t\t\t\tservice.Name, s, g.Name, listener,\n\t\t\t\t\t)\n\t\t\t\t}\n\t\t\t\tlisteners[listener] = service.Name\n\t\t\t}\n\n\t\t\tif tp := service.Connect.SidecarService.Proxy.TransparentProxy; tp != nil {\n\t\t\t\thasTproxy = true\n\t\t\t\tfor _, net := range g.Networks {\n\t\t\t\t\tif !net.DNS.IsZero() && !tp.NoDNS {\n\t\t\t\t\t\treturn fmt.Errorf(\n\t\t\t\t\t\t\t\"Consul Connect transparent proxy cannot be used with network.dns unless no_dns=true\")\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tfor _, portLabel := range tp.ExcludeInboundPorts {\n\t\t\t\t\tif !transparentProxyPortLabelValidate(g, portLabel) {\n\t\t\t\t\t\treturn fmt.Errorf(\n\t\t\t\t\t\t\t\"Consul Connect transparent proxy port %q must be numeric or one of network.port labels\", portLabel)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t}\n\t}\n\tif hasTproxy && connectBlockCount > 1 {\n\t\treturn fmt.Errorf(\"Consul Connect transparent proxy requires there is only one connect block\")\n\t}\n\treturn nil\n}\n\nfunc transparentProxyPortLabelValidate(g *structs.TaskGroup, portLabel string) bool {\n\tif _, err := strconv.ParseUint(portLabel, 10, 16); err == nil {\n\t\treturn true\n\t}\n","sourceCodeStart":587,"sourceCodeEnd":623,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/job_endpoint_hook_connect.go#L587-L623","documentation":"Each entry in `transparent_proxy.exclude_inbound_ports` must either be a raw numeric port (0-65535) or a port label defined in the group's `network { port \"label\" {} }` stanza. transparentProxyPortLabelValidate rejects anything else, and groupConnectUpstreamsValidate surfaces this error at job validation time.","triggerScenarios":"Submit a job whose transparent_proxy block lists an exclude_inbound_ports entry that is neither parseable as a uint16 nor matches any `network.port` label in the task group (e.g. a service name, a typo'd port label, or a port number > 65535).","commonSituations":"Writing a destination service name instead of a port or label in exclude_inbound_ports; port labels that exist on a different task group; forgetting to declare the corresponding network.port label in the same group; typos like \"8443/tcp\".","solutions":["Change the entry to a numeric port (e.g. \"9090\") if excluding a literal port.","Or declare a matching port label in the group's network stanza: `network { port \"metrics\" {} }` and use `exclude_inbound_ports = [\"metrics\"]`.","Fix typos so the label exactly matches an existing `network.port` label in the same group.","Remove invalid entries that are neither ports nor labels."],"exampleFix":"// before\ntransparent_proxy {\n  exclude_inbound_ports = [\"count-api\"]\n}\n// after\nnetwork {\n  port \"count_api\" {}\n}\ntransparent_proxy {\n  exclude_inbound_ports = [\"count_api\"]\n}","handlingStrategy":"validation","validationCode":"// Every exclude_inbound_ports entry must be numeric (uint16) or a declared network port label.\nfunction validateExcludePorts(group) {\n  const labels = new Set((group.networks ?? []).flatMap(n => Object.keys(n.port ?? {})));\n  for (const s of group.services ?? []) {\n    const tp = s.connect?.sidecar_service?.proxy?.transparent_proxy;\n    if (!tp) continue;\n    for (const p of tp.exclude_inbound_ports ?? []) {\n      const numeric = /^\\d+$/.test(p) && Number(p) <= 65535;\n      if (!numeric && !labels.has(p)) throw new Error(`invalid exclude_inbound_ports entry: ${p}`);\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use port labels that are declared in the SAME task group's network stanza.","Exclude literal ports as numeric strings; never put service names in exclude_inbound_ports.","Cross-check labels against network.port definitions after renaming ports in templates."],"tags":["consul-connect","transparent-proxy","port-label","nomad-job-spec","validation"],"backgroundTag":"invalid-port-label","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"}