hashicorp/nomad · error

%s: %w: group %q uses network mode %q; must be %s

Error message

%s: %w: group %q uses network mode %q; must be %s

What it means

When a connect-enabled group has exactly one network, its mode must be "bridge" (or "host" when explicitly allowed, e.g. for expose checks) or a "cni/..." prefixed mode. Nomad rejects connect groups whose network mode is anything else, with a message listing the allowed modes for the given context.

Source

Thrown at nomad/job_endpoint_hook_connect.go:650

}

func groupConnectNetworkModeValidate(g *structs.TaskGroup, errorPrefix string, allowHost bool) error {
	if nn := len(g.Networks); nn != 1 {
		return fmt.Errorf("%s: %w: group %q has %d networks",
			errorPrefix, ErrConnectRequireOneNetwork, g.Name, nn)
	}

	mode := g.Networks[0].Mode
	if mode == "bridge" || (allowHost && mode == "host") || strings.HasPrefix(mode, "cni/") {
		return nil
	}

	// helpful error message
	allowed := `"bridge" or "cni/*"`
	if allowHost {
		allowed = `"bridge", "host", or "cni/*"`
	}
	return fmt.Errorf("%s: %w: group %q uses network mode %q; must be %s",
		errorPrefix, ErrConnectInvalidNetworkMode, g.Name, mode, allowed)
}

func groupConnectSidecarValidate(g *structs.TaskGroup, s *structs.Service) error {
	if err := groupConnectNetworkModeValidate(g, "connect sidecar", false); err != nil {
		return err
	}

	// We must enforce lowercase characters on group and service names for connect
	// sidecar proxies, because Consul assumes this invariant without validating it.
	// https://github.com/hashicorp/consul/blob/v1.9.5/command/connect/proxy/proxy.go#L235

	if s.Name != strings.ToLower(s.Name) {
		return fmt.Errorf("Consul Connect service name %q in group %q must not contain uppercase characters", s.Name, g.Name)
	}

	if g.Name != strings.ToLower(g.Name) {
		return fmt.Errorf("Consul Connect group %q with service %q must not contain uppercase characters", g.Name, s.Name)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the group network `mode = "bridge"` (the default for connect).
2. If using a CNI plugin, prefix the mode with "cni/" (e.g. mode = "cni/calico").
3. For host networking with connect, only host networking is allowed in the expose-check context; otherwise restructure to use bridge mode.

Example fix

// before
group "web" {
  network {
    mode = "host"
    port "http" {}
  }
  service {
    connect { sidecar_service {} }
  }
}
// after
group "web" {
  network {
    mode = "bridge"
    port "http" {}
  }
  service {
    connect { sidecar_service {} }
  }
}

function validateConnectNetworkMode(group, allowHost = false) {
  const mode = group.networks?.[0]?.mode;
  const ok = mode === "bridge" || (allowHost && mode === "host") || String(mode).startsWith("cni/");
  if (!ok) throw new Error(`group "${group.name}" network mode "${mode}" not allowed for connect`);
}

function isConnectCompatibleMode(mode, allowHost = false) { return mode === "bridge" || (allowHost && mode === "host") || (typeof mode === 'string' && mode.startsWith('cni/')); }

When it happens

Trigger: Submitting a job where a group's single network block uses mode "host" for a connect sidecar (allowHost=false), or a mode like "mesh-gateway"/custom non-cni mode, via groupConnectSidecarValidate, groupConnectGatewayValidate, or tgValidateExposeNetworkMode.

Common situations: Users setting `mode = "host"` on a group network because that is common for non-connect workloads; copy-paste of network stanzas from non-connect jobs; CNI plugin setups where a mode string not starting with "cni/" was used; upgrading Nomad and migrating host-networked connect services.

Related errors

• ErrConnectInvalidNetworkMode
• ErrConnectRequireOneNetwork
• service.port must be set for mesh gateway service
• %s: %w: group %q has %d networks
• Consul Connect service name %q in group %q must not contain

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