invalid Consul Connect configuration for service %q: %v

Error message

invalid Consul Connect configuration for service %q: %v

What it means

newConnect builds the Consul Connect SidecarService registration block for a Connect-enabled service; if the Connect configuration cannot be translated into a valid Consul registration (bad connect stanza, invalid sidecar port, incompatible workload networks), this wrapper aborts the service registration. It only fires for services that declare a Connect block.

Source

Thrown at command/agent/consul/service_client.go:1350

		service.Address, addrMode, service.PortLabel, workload.Networks, workload.DriverNetwork, workload.Ports, workload.NetworkStatus)
	if err != nil {
		return nil, fmt.Errorf("unable to get address for service %q: %v", service.Name, err)
	}

	// Determine whether to use tags or canary_tags
	var tags []string
	if workload.Canary && len(service.CanaryTags) > 0 {
		tags = make([]string, len(service.CanaryTags))
		copy(tags, service.CanaryTags)
	} else {
		tags = make([]string, len(service.Tags))
		copy(tags, service.Tags)
	}

	// newConnect returns (nil, nil) if there's no Connect-enabled service.
	connect, err := newConnect(id, workload.AllocInfo, service.Name, service.Connect, workload.Networks, workload.Ports)
	if err != nil {
		return nil, fmt.Errorf("invalid Consul Connect configuration for service %q: %v", service.Name, err)
	}

	// newConnectGateway returns nil if there's no Connect gateway.
	gateway := newConnectGateway(service.Connect)

	// newWeights returns nil if there's no Weights.
	weights := newWeights(service.Weights)

	// Determine whether to use meta or canary_meta
	var meta map[string]string
	if workload.Canary && len(service.CanaryMeta) > 0 {
		meta = make(map[string]string, len(service.CanaryMeta)+1)
		maps.Copy(meta, service.CanaryMeta)
	} else {
		meta = make(map[string]string, len(service.Meta)+1)
		maps.Copy(meta, service.Meta)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Fix the connect block per the wrapped error — most often the sidecar port or missing group network declaration
Ensure the task group declares a network with the ports referenced by sidecar_service
Validate connect { sidecar_task {} } resource/config options against your Consul/Nomad version
Temporarily remove the connect block to isolate which field is invalid, then re-add

Example fix

// before
connect {
  sidecar_service {
    port = "proxy" // not declared
  }
}
// after
network {
  port "proxy" {}
}
connect {
  sidecar_service {
    port = "proxy"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate connect sidecar references before submit
if svc.Connect != nil && svc.Connect.SidecarService != nil {
  if p := svc.Connect.SidecarService.Port; p != "" {
    if _, ok := ports[p]; !ok {
      return fmt.Errorf("connect sidecar port %q not declared", p)
    }
  }
}

Prevention

Declare a network port for the proxy in the group network block
Keep connect blocks to the documented sidecar_service/sidecar_task fields
Match envoy options to your Consul version
Test connect jobs with `nomad job validate` first

When it happens

Trigger: service.Connect is non-nil but newConnect(id, allocInfo, name, connect, networks, ports) returns an error — e.g. the Connect sidecar_service references a missing port, the sidecar task stanza is invalid, or the service group has no usable network for the envoy proxy.

Common situations: Consul Connect block with sidecar_service.port referencing a nonexistent port label; connect { sidecar_task {} } with invalid resources; envoy settings incompatible with the Consul version; missing network declaration in the group.

Related errors

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