Consul Connect transparent proxy requires there is only one

Error message

Consul Connect transparent proxy requires there is only one connect block

What it means

Transparent proxy mode assumes a single Consul Connect sidecar per task group: with more than one connect block, iptables-based interception cannot be attributed consistently. After validating all services, groupConnectUpstreamsValidate checks the accumulated hasTproxy flag against connectBlockCount and fails the job if a transparent proxy is enabled while multiple connect blocks exist.

Source

Thrown at nomad/job_endpoint_hook_connect.go:614

				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
	}

	for _, network := range g.Networks {
		for _, reservedPort := range network.ReservedPorts {
			if reservedPort.Label == portLabel {
				return true
			}
		}
	}
	return false
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Move the second connect-enabled service into a different task group.
Disable `transparent_proxy {}` (use explicit upstreams) if multiple connect services must share one group.
Consolidate multiple connect services into a single connect block where possible.

Example fix

// before (one group)
group "web" {
  service "a" { connect { sidecar_service { proxy { transparent_proxy {} } } } }
  service "b" { connect { sidecar_service {} } }
}
// after (split groups)
group "web-a" {
  service "a" { connect { sidecar_service { proxy { transparent_proxy {} } } } }
}
group "web-b" {
  service "b" { connect { sidecar_service {} } }
}

Defensive patterns

Strategy: validation

Validate before calling

// Transparent proxy requires exactly one connect block per task group.
function validateTproxySingleConnect(group) {
  const connectCount = (group.services ?? []).filter(s => s.connect).length;
  const hasTproxy = (group.services ?? []).some(s => s.connect?.sidecar_service?.proxy?.transparent_proxy);
  if (hasTproxy && connectCount > 1) throw new Error(`group ${group.name}: transparent proxy requires a single connect block`);
}

Prevention

Design task groups so each transparent-proxy service lives in its own group.
Add a lint rule over HCL/JSON job specs rejecting >1 connect block when transparent_proxy is present.
When adding a new connect service to a group, check existing services for transparent proxy first.

When it happens

Trigger: Job submission where a single task group contains two or more `service { connect { sidecar_service ... } }` blocks and at least one of them sets `proxy.transparent_proxy {}`.

Common situations: Scaling an existing group's services to more connect-enabled services after one was migrated to transparent proxy; copy-pasting a connect service block into a group that already uses transparent proxy; misunderstanding that the one-connect-block limit is per task group, not per job.

Related errors

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