hashicorp/nomad · error

Consul Connect transparent proxy cannot be used with network

Error message

Consul Connect transparent proxy cannot be used with network.dns unless no_dns=true

What it means

When a Connect service configures a transparent proxy (`transparent_proxy {}`), the sidecar intercepts all traffic, which conflicts with task-group `network { dns {...} }` settings unless the user explicitly opts out with `no_dns = true`. Nomad's groupConnectUpstreamsValidate hook returns this error at job validation time when a network block has DNS servers/options and the transparent proxy does not set NoDNS.

Source

Thrown at nomad/job_endpoint_hook_connect.go:599

				if up.LocalBindSocketPath == "" {
					listener = net.JoinHostPort(up.LocalBindAddress, strconv.Itoa(up.LocalBindPort))
				} else {
					listener = up.LocalBindSocketPath
				}
				if s, exists := listeners[listener]; exists {
					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
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set `no_dns = true` inside the `transparent_proxy {}` block to acknowledge DNS is handled separately.
2. Remove the `dns` block from the group's `network` stanza since transparent proxy traffic will not honor it.
3. Drop `transparent_proxy {}` if you actually need per-group DNS customization via the bridge network.

Example fix

// before
network {
  dns { servers = ["10.0.0.10"] }
}
service {
  connect { sidecar_service { proxy { transparent_proxy {} } } }
}
// after
network {
  dns { servers = ["10.0.0.10"] }
}
service {
  connect { sidecar_service { proxy { transparent_proxy { no_dns = true } } } }
}

// Reject transparent proxy + network.dns without no_dns before submission.
function validateTproxyDns(groups) {
  for (const g of groups) {
    const hasDns = (g.networks ?? []).some(n => n.dns && (n.dns.servers?.length || n.dns.options?.length));
    for (const s of g.services ?? []) {
      const tp = s.connect?.sidecar_service?.proxy?.transparent_proxy;
      if (tp && hasDns && tp.no_dns !== true) {
        throw new Error(`group ${g.name}: transparent_proxy needs no_dns=true or no network.dns`);
      }
    }
  }
}

When it happens

Trigger: Job submission (validate/plan/run) where for some service in the group, `connect.sidecar_service.proxy.transparent_proxy` is set, a network in `g.Networks` has a non-zero `dns` block, and `transparent_proxy.no_dns` is not true.

Common situations: Adding a transparent proxy to an existing group that already configured custom DNS servers for the group's bridge network; templates converted from Consul config entries where DNS coexistence was allowed; users unaware the sidecar's iptables interception overrides group DNS settings.

Related errors

• Consul Connect transparent proxy port %q must be numeric or
• Consul Connect transparent proxy requires there is only one
• Consul Connect services %q and %q in group %q using same add
• network hostname %q is not a valid DNS name
• transparent proxy block has invalid UID field: %w

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