What causes "invalid network mode for Consul Connect" in hashicorp/nomad?

Set the group network mode to "bridge" for Connect sidecars (or "host" where host networking is required, e.g. with transparent proxy setups).

hashicorp/nomad · error

ErrConnectInvalidNetworkMode

ErrConnectInvalidNetworkMode

Error message

invalid network mode for Consul Connect

What it means

When a task group uses Consul Connect, its single network must use a mode compatible with Connect (bridge for sidecars, or host for host-mode services/gateways). Nomad rejects the job if the declared network mode is not one of the allowed values.

Source

Thrown at nomad/job_endpoint_hook_connect.go:29

	"strings"
	"time"

	"github.com/hashicorp/go-set/v3"
	"github.com/hashicorp/nomad/client/taskenv"
	"github.com/hashicorp/nomad/helper/envoy"
	"github.com/hashicorp/nomad/helper/uuid"
	"github.com/hashicorp/nomad/nomad/structs"
)

const (
	// defaultConnectTimeout is the default amount of time a connect gateway will
	// wait for a response from an upstream service (same as consul)
	defaultConnectTimeout = 5 * time.Second
)

var (
	ErrConnectRequireOneNetwork  = errors.New("must have exactly one network for Consul Connect")
	ErrConnectInvalidNetworkMode = errors.New("invalid network mode for Consul Connect")
)

// connectSidecarResources returns the set of resources used by default for
// the Consul Connect sidecar task
func connectSidecarResources() *structs.Resources {
	return &structs.Resources{
		CPU:      250,
		MemoryMB: 128,
	}
}

// connectSidecarDriverConfig is the driver configuration used by the injected
// connect proxy sidecar task.
//
// Note: must be compatible with both docker and podman. One could imagine passing
// in the driver name in the future and switching on that if we need specific
// configs.
func connectSidecarDriverConfig() map[string]any {

View on GitHub (pinned to 482b49bf1a)

Solutions

Set the group network mode to "bridge" for Connect sidecars (or "host" where host networking is required, e.g. with transparent proxy setups).
Check the allowed modes listed in the full error message and match one exactly.
Remove the explicit network mode to let Nomad apply the Connect default.

Example fix

// before
network {
  mode = "none"
}
connect { sidecar_service {} }

// after
network {
  mode = "bridge"
}
connect { sidecar_service {} }

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"bridge": true, "host": true}
if group.Connect != nil && (len(group.Networks) != 1 || !allowed[group.Networks[0].Mode]) {
  return fmt.Errorf("group %q: connect network mode %q not allowed", group.Name, group.Networks[0].Mode)
}

Prevention

Always declare network mode explicitly on connect groups
Match the mode suggested by the full error message's allowed list
Consult Nomad docs for mode requirements per gateway kind

When it happens

Trigger: Submitting a connect-enabled group whose single network block has a `mode` value outside the allowed set (e.g. mode = "none", or a host network on a sidecar that requires bridge).

Common situations: Setting network mode = "host" for a sidecar proxy that needs bridge; typo in mode string; copying a non-connect group's network config into a connect group.

Related errors

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