Consul Connect transparent proxy port %q must be numeric or

Error message

Consul Connect transparent proxy port %q must be numeric or one of network.port labels

What it means

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.

Source

Thrown at nomad/job_endpoint_hook_connect.go:605

					return fmt.Errorf(
						"Consul Connect services %q and %q in group %q using same address for upstreams (%s)",
						service.Name, s, g.Name, listener,
					)
				}
				listeners[listener] = service.Name
			}

			if tp := service.Connect.SidecarService.Proxy.TransparentProxy; tp != nil {
				hasTproxy = true
				for _, net := range g.Networks {
					if !net.DNS.IsZero() && !tp.NoDNS {
						return fmt.Errorf(
							"Consul Connect transparent proxy cannot be used with network.dns unless no_dns=true")
					}
				}
				for _, portLabel := range tp.ExcludeInboundPorts {
					if !transparentProxyPortLabelValidate(g, portLabel) {
						return fmt.Errorf(
							"Consul Connect transparent proxy port %q must be numeric or one of network.port labels", portLabel)
					}
				}
			}

		}
	}
	if hasTproxy && connectBlockCount > 1 {
		return fmt.Errorf("Consul Connect transparent proxy requires there is only one connect block")
	}
	return nil
}

func transparentProxyPortLabelValidate(g *structs.TaskGroup, portLabel string) bool {
	if _, err := strconv.ParseUint(portLabel, 10, 16); err == nil {
		return true
	}

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before
transparent_proxy {
  exclude_inbound_ports = ["count-api"]
}
// after
network {
  port "count_api" {}
}
transparent_proxy {
  exclude_inbound_ports = ["count_api"]
}

Defensive patterns

Strategy: validation

Validate before calling

// Every exclude_inbound_ports entry must be numeric (uint16) or a declared network port label.
function validateExcludePorts(group) {
  const labels = new Set((group.networks ?? []).flatMap(n => Object.keys(n.port ?? {})));
  for (const s of group.services ?? []) {
    const tp = s.connect?.sidecar_service?.proxy?.transparent_proxy;
    if (!tp) continue;
    for (const p of tp.exclude_inbound_ports ?? []) {
      const numeric = /^\d+$/.test(p) && Number(p) <= 65535;
      if (!numeric && !labels.has(p)) throw new Error(`invalid exclude_inbound_ports entry: ${p}`);
    }
  }
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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".

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/880746a06f2cea7a. Report an issue: GitHub.