Connect only supported with exactly 1 network (found %d)

Error message

Connect only supported with exactly 1 network (found %d)

What it means

connectNetworkInvariants enforces that Connect proxy logic receives exactly one network from the allocation. Connect sidecar registrations map a single task network to a Consul sidecar; with zero or multiple networks the mapping is ambiguous, so an error is thrown.

Source

Thrown at command/agent/consul/connect.go:312

		return
	}

	// common case.
	var tags []string
	for key, value := range defaultTags {
		if value == "" {
			continue
		}
		tag := key + value
		tags = append(tags, tag)
	}
	sort.Strings(tags) // mostly for test stability
	cfg[configKey] = tags
}

func connectNetworkInvariants(networks structs.Networks) error {
	if n := len(networks); n != 1 {
		return fmt.Errorf("Connect only supported with exactly 1 network (found %d)", n)
	}
	return nil
}

// connectPort returns the network and port for the Connect proxy sidecar
// defined for this service. An error is returned if the network and port
// cannot be determined.
func connectPort(portLabel string, networks structs.Networks, ports structs.AllocatedPorts) (structs.AllocatedPortMapping, error) {
	if err := connectNetworkInvariants(networks); err != nil {
		return structs.AllocatedPortMapping{}, err
	}
	mapping, ok := ports.Get(portLabel)
	if !ok {
		mapping = networks.Port(portLabel)
		if mapping.Value > 0 {
			return mapping, nil
		}
		return structs.AllocatedPortMapping{}, fmt.Errorf("No port of label %q defined", portLabel)

View on GitHub (pinned to 482b49bf1a)

Solutions

Ensure the task declares exactly one network block when using Connect services.
Collapse multiple network stanzas into a single block with multiple ports.
Migrate to the modern 'network { port "x" {} }' single-network model required by Connect.

Example fix

// before
network {
  mode = "bridge"
  port "http" {}
}
network {
  port "admin" {}
}
// after
network {
  mode = "bridge"
  port "http" {}
  port "admin" {}
}

Defensive patterns

Strategy: validation

Validate before calling

if len(task.Networks) != 1 {
  return fmt.Errorf("task %s: Connect requires exactly 1 network, found %d", task.Name, len(task.Networks))
}

Prevention

Use a single network block per task when using Connect.
Merge ports into one network stanza.
Audit legacy multi-network job specs.

When it happens

Trigger: connectPort or connectExposePathPort invoked with an allocation whose task 'networks' list has a length other than 1 — no network declared, or multiple network stanzas on the task.

Common situations: Job files with more than one network block per task (pre-1.x style networking) combined with Connect services, or tasks missing a network stanza while declaring connect-enabled services.

Related errors

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