hashicorp/nomad · error

ErrConnectRequireOneNetwork

ErrConnectRequireOneNetwork

Error message

must have exactly one network for Consul Connect

What it means

Nomad's Consul Connect integration requires each task group with a connect block to declare exactly one network stanza. The job submission endpoint returns this error wrapped with the group name and the offending network count when that invariant is violated.

Source

Thrown at nomad/job_endpoint_hook_connect.go:28

	"strconv"
	"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.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the connect-enabled task group declares exactly one network block (typically `network { mode = "bridge" }`).
2. Remove extra network stanzas so only one remains in the group.
3. If a connect service port is needed, use the existing single network's port/dynamic port rather than adding a second network.

Example fix

// before
group "api" {
  network {
    mode = "bridge"
  }
  network {
    mode = "host"
  }
  connect { sidecar_service {} }
}

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

// HCL/Job check before submit
if group.Connect != nil && len(group.Networks) != 1 {
  return fmt.Errorf("group %q: connect requires exactly one network, has %d", group.Name, len(group.Networks))
}

When it happens

Trigger: Submitting a job whose task group has a `connect { sidecar_service ... }` (or gateway) block while `group.Networks` has length != 1 (0 networks, or 2+ networks). Validation runs in groupConnectNetworkModeValidate via the job mutate/validate hook.

Common situations: Adding a connect service to a group that previously had no network block; accidentally specifying two network stanzas (e.g. bridge + host) on a connect-enabled group; copy-pasting network config from another group.

Related errors

• %s: %w: group %q has %d networks
• ErrConnectInvalidNetworkMode
• service.port must be set for mesh gateway service
• %s: %w: group %q uses network mode %q; must be %s
• 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/03db902de4305d18. Report an issue: GitHub.