What causes "No port of label %q defined" in hashicorp/nomad?

Add the missing port label to the task's network block so it matches the service's port_label.

No port of label %q defined

Error message

No port of label %q defined

What it means

connectPort resolves the host port for a Connect sidecar from the service's PortLabel. When the label cannot be found in the allocation's ports (explicit Ports map or the task networks), and no positive port value exists, this error is returned.

Source

Thrown at command/agent/consul/connect.go:330

		return fmt.Errorf("Connect only supported with exactly 1 network (found %d)", n)
	}
	return nil
}

// connectPort returns the network and port for the Connect proxy sidecar
// defined for this service. An error is returned if the network and port
// cannot be determined.
func connectPort(portLabel string, networks structs.Networks, ports structs.AllocatedPorts) (structs.AllocatedPortMapping, error) {
	if err := connectNetworkInvariants(networks); err != nil {
		return structs.AllocatedPortMapping{}, err
	}
	mapping, ok := ports.Get(portLabel)
	if !ok {
		mapping = networks.Port(portLabel)
		if mapping.Value > 0 {
			return mapping, nil
		}
		return structs.AllocatedPortMapping{}, fmt.Errorf("No port of label %q defined", portLabel)
	}
	return mapping, nil
}

// connectExposePathPort returns the port for the exposed path for the exposed
// proxy path.
func connectExposePathPort(portLabel string, networks structs.Networks) (string, int, error) {
	if err := connectNetworkInvariants(networks); err != nil {
		return "", 0, err
	}

	mapping := networks.Port(portLabel)
	if mapping.Value == 0 {
		return "", 0, fmt.Errorf("No port of label %q defined", portLabel)
	}

	return mapping.HostIP, mapping.Value, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Add the missing port label to the task's network block so it matches the service's port_label.
Fix the port_label spelling to match an existing port definition.
Run nomad job validate to catch label mismatches before submission.

Example fix

// before
connect { sidecar_service {} } // service port_label = "http"
// but network has no http port
// after
network {
  mode = "bridge"
  port "http" {}
}

Defensive patterns

Strategy: validation

Validate before calling

for _, svc := range task.Services {
  if _, ok := ports[svc.PortLabel]; !ok {
    return fmt.Errorf("service %s: port label %q undefined", svc.Name, svc.PortLabel)
  }
}

Prevention

Cross-check every service port_label against the network block.
Use nomad job validate as a pre-submit gate.
Keep port label names consistent between network and service stanzas.

When it happens

Trigger: A connect-enabled service (or its sidecar_service) references a port_label that does not exist in the task's network ports, or the mapped port value is 0.

Common situations: Typos in port labels, port defined on a different task's network, port block omitted from the network stanza, or dynamic ports not allocated yet.

Related errors

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