service %q cannot use address_mode="driver", only services d

Error message

service %q cannot use address_mode="driver", only services defined in a "task" block can use this mode

What it means

address_mode="driver" (use the address/port reported by the task driver, e.g. Docker) is only valid for services defined inside a task block, because only task-level context has driver-provided addresses. A group-level service using this mode is rejected.

Source

Thrown at nomad/structs/structs.go:7539

		id := unique{service.Name, "group", service.PortLabel}
		if !idSet.Insert(id) {
			// accumulate duplicates for a single error later on
			idDuplicateSet.Insert(id)
		}

		// Track that we have seen this service provider
		providerSet.Insert(service.Provider)

		if err := service.Validate(); err != nil {
			outer := fmt.Errorf("Service[%d] %s validation failed: %s", i, service.Name, err)
			mErr.Errors = append(mErr.Errors, outer)
			// we break here to avoid the risk of crashing on null-pointer
			// access in a later step, accepting that we might miss out on
			// error messages to provide the user.
			continue
		}
		if service.AddressMode == AddressModeDriver {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("service %q cannot use address_mode=\"driver\", only services defined in a \"task\" block can use this mode", service.Name))
		}

		for _, check := range service.Checks {
			if check.TaskName != "" {
				if check.AddressMode == AddressModeDriver {
					mErr.Errors = append(mErr.Errors, fmt.Errorf("Check %q invalid: cannot use address_mode=\"driver\", only checks defined in a \"task\" service block can use this mode", service.Name))
				}
				if !taskSet.Contains(check.TaskName) {
					mErr.Errors = append(mErr.Errors,
						fmt.Errorf("Check %s invalid: refers to non-existent task %s", check.Name, check.TaskName))
				}
			}
		}
	}

	// Produce an error of any services which are not unique enough in the group
	// i.e. have same <task, name, port>
	if idDuplicateSet.Size() > 0 {

View on GitHub (pinned to 482b49bf1a)

Solutions

Set address_mode = "host" (or "auto") on the group-level service.
Move the service into the task block if driver-reported addresses are required.
Use host_network/port labels that resolve at group level.

Example fix

// before
group "g" { service { name="s" address_mode="driver" } }
// after
group "g" { service { name="s" address_mode="host" port="http" } }

Defensive patterns

Strategy: validation

Validate before calling

if scope == "group" && svc.AddressMode == "driver" {
  return fmt.Errorf("service %q: address_mode=driver not allowed at group level", svc.Name)
}

Prevention

Use address_mode=host/auto in group services
Reserve driver mode for task-block services only
Document scope rules in internal job templates

When it happens

Trigger: A group-level services block sets address_mode = "driver"; validation appends this error for service.AddressMode == AddressModeDriver at group scope.

Common situations: Moving a service from a task to the group to share it, without switching address_mode from driver to host/auto; docs or examples written for task services applied at group level.

Related errors

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