Service %s is Connect Native and requires setting the port

Error message

Service %s is Connect Native and requires setting the port

What it means

A Connect Native service must have a port label on the service stanza; Consul rejects native registrations without a port. validateConsulService enforces this when Connect.IsNative() is true and s.PortLabel is empty.

Source

Thrown at nomad/structs/services.go:900

	default:
		mErr.Errors = append(mErr.Errors, fmt.Errorf("Service %s kind must be one of consul service kind or empty", s.Name))
	}

	// check connect
	if s.Connect != nil {
		if err := s.Connect.Validate(); err != nil {
			mErr.Errors = append(mErr.Errors, err)
		}

		// if service is connect native, service task must be set (which may
		// happen implicitly in a job mutation if there is only one task)
		if s.Connect.IsNative() && len(s.TaskName) == 0 {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Service %s is Connect Native and requires setting the task", s.Name))
		}

		// if service is connect native a port must be set on the service or consul will reject it
		if s.Connect.IsNative() && s.PortLabel == "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Service %s is Connect Native and requires setting the port", s.Name))
		}
	}
}

// validateNomadService performs validation on a service which is using the
// nomad provider.
func (s *Service) validateNomadService(mErr *multierror.Error) {
	// check checks
	for _, c := range s.Checks {
		// validate the check port
		if err := s.validateCheckPort(c); err != nil {
			mErr.Errors = append(mErr.Errors, err)
			continue
		}

		// validate the nomad check
		if err := c.validateNomad(); err != nil {
			mErr.Errors = append(mErr.Errors, err)

View on GitHub (pinned to 482b49bf1a)

Solutions

Add `port = "<label>"` to the service stanza, matching a port defined in the task's network stanza.
Ensure the task network stanza declares the referenced port.
If no inbound port is truly needed, keep the port set anyway — Consul requires it for native services.

Example fix

// before
service {
  name = "native-svc"
  task = "app"
  connect { sidecar_service {} }
}
// after
service {
  name = "native-svc"
  task = "app"
  port = "http"
  connect { sidecar_service {} }
}

Defensive patterns

Strategy: validation

Validate before calling

if svc.Connect != nil && svc.Connect.IsNative() && svc.PortLabel == "" {
  return fmt.Errorf("connect-native service %q must set port", svc.Name)
}

Prevention

Always pair connect-native services with a port label from the task network stanza
Declare the referenced port in the task's network block
Run `nomad job validate` in CI on every job change

When it happens

Trigger: A Connect Native service (connect stanza with native usage) whose service stanza has no `port` field and whose check/port configuration leaves PortLabel empty.

Common situations: Writing Connect Native services without a port because the app listens on a Unix socket or doesn't need inbound traffic; copying sidecar-based examples that omit ports.

Related errors

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