Connect only supported with exactly 1 network

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.

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.

Appendix: 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)