hashicorp/nomad · error

Consul Connect must be exclusively native, make use of a sid

Error message

Consul Connect must be exclusively native, make use of a sidecar, or represent a Gateway

What it means

Connect.Validate counts the mutually exclusive Connect modes — IsNative(), a SidecarService, and IsGateway() — and requires exactly one. Setting more than one (or none) makes the connect stanza ambiguous, so it is rejected. If it is a gateway, the gateway block itself is then validated.

Source

Thrown at nomad/structs/services.go:1361

	if c.HasSidecar() {
		if c.HasTransparentProxy() {
			if err := c.SidecarService.Proxy.TransparentProxy.Validate(); err != nil {
				return err
			}
		}
		count++
	}

	if c.IsNative() {
		count++
	}

	if c.IsGateway() {
		count++
	}

	if count != 1 {
		return fmt.Errorf("Consul Connect must be exclusively native, make use of a sidecar, or represent a Gateway")
	}

	if c.IsGateway() {
		if err := c.Gateway.Validate(); err != nil {
			return err
		}
	}

	// Checking against the surrounding task group is validated up at the
	// service level or job endpint connect validation hook

	return nil
}

// ConsulSidecarService represents a Consul Connect SidecarService jobspec
// block.
type ConsulSidecarService struct {
	// Tags are optional service tags that get registered with the sidecar service

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Keep exactly one of: sidecar_service, native, or gateway inside the connect stanza and delete the others.
2. Remove the connect stanza entirely if the service should not use Connect.
3. If converting to a gateway service, drop sidecar_service and keep only the gateway block.

Example fix

// before
connect {
  sidecar_service {}
  gateway {
    ingress {}
  }
}
// after
connect {
  gateway {
    ingress {}
  }
}

func connectModeCount(c Connect) int {
  n := 0
  if c.IsNative() { n++ }
  if c.SidecarService != nil { n++ }
  if c.IsGateway() { n++ }
  return n
}
if connectModeCount(conn) != 1 { return errors.New("connect must set exactly one of native, sidecar_service, or gateway") }

When it happens

Trigger: A connect stanza with both sidecar_service and native config; a connect stanza with a gateway plus sidecar_service; an empty connect {} block with none of the three.

Common situations: Merging service stanzas from different examples; converting a sidecar service to native and leaving leftovers; copy-paste across gateway and non-gateway services.

Related errors

• wait config is nil or empty
• missing datacenter for client registration
• default_identity_ttl must be greater than 0
• max_identity_ttl must be greater than 0
• max_identity_ttl must be greater than or equal to default_id

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