check %q cannot use address_mode="alloc", only checks define

Error message

check %q cannot use address_mode="alloc", only checks defined in a "group" service block can use this mode

What it means

A check may only use address_mode="alloc" when its parent service is defined in a "group" block. Like services, checks resolve the allocation address only in group context; task-level checks must use driver/host addressing. The error (using the service's name) is appended during service validation.

Source

Thrown at nomad/structs/structs.go:8527

				addServicePort(service.PortLabel, service.Name)
			}
		}

		// connect block is only allowed on group level
		if service.Connect != nil {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("service %q cannot have \"connect\" block, only services defined in a \"group\" block can", service.Name))
		}

		// Ensure that check names are unique and have valid ports
		knownChecks := make(map[string]struct{})
		for _, check := range service.Checks {
			if _, ok := knownChecks[check.Name]; ok {
				mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q is duplicate", check.Name))
			}
			knownChecks[check.Name] = struct{}{}

			if check.AddressMode == AddressModeAlloc {
				mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q cannot use address_mode=\"alloc\", only checks defined in a \"group\" service block can use this mode", service.Name))
			}

			if check.AddressMode == AddressModeAllocIPv6 {
				mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q cannot use address_mode=\"alloc_ipv6\", only checks defined in a \"group\" service block can use this mode", service.Name))
			}

			if !check.RequiresPort() {
				// No need to continue validating check if it doesn't need a port
				continue
			}

			effectivePort := check.PortLabel
			if effectivePort == "" {
				// Inherits from service
				effectivePort = service.PortLabel
			}

			if effectivePort == "" {

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove address_mode="alloc" from the check, or change it to "host"/"driver".
Move the parent service to the group level if alloc addressing is genuinely required.
Run `nomad job validate` to verify all address modes resolve correctly.

Example fix

// before
task "app" {
  service {
    name = "api"
    check { name = "live"; address_mode = "alloc"; port = "8080" }
  }
}

// after
task "app" {
  service {
    name = "api"
    check { name = "live"; port = "8080" }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

for taskLevelChecks {
  if c.AddressMode == "alloc" {
    return fmt.Errorf("check %q: alloc address_mode requires a group-level service", c.Name)
  }
}

Prevention

Do not set address_mode on checks under task-level services
Centralize alloc-mode checks in group-level service blocks
Validate the job before submission in CI

When it happens

Trigger: Submitting a job with a check inside a task-level service where check.address_mode = "alloc" (AddressModeAlloc).

Common situations: Mirroring a group-level check configuration into a task; assuming check address_mode is independent of service placement; IPv6/alloc-mode experimentation in the wrong scope.

Related errors

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