group %q references task %q in a service definition, but the

Error message

group %q references task %q in a service definition, but the task has no shutdown_delay set

What it means

A warning from TaskGroup.Warnings: when the group's service definition references a task by name (via SidecarTask-like task references tracked in referencedTaskIDs) and that task's ShutdownDelay is 0, Nomad warns that the referenced task has no shutdown_delay. This helps ensure graceful draining for connect sidecars and service churn.

Source

Thrown at nomad/structs/structs.go:4932

			referencedTaskIDs[s.TaskName] = struct{}{}
			continue
		}

		if s.Connect != nil && s.Connect.SidecarTask != nil {
			if s.Connect.SidecarTask.ShutdownDelay == nil {
				warnings = append(warnings, fmt.Errorf(
					"service %q defines a sidecar task in Consul Connect definition, but the task has no shutdown_delay set",
					s.Name))
			}
			continue
		}

		hasUnscopedGroupService = true
	}

	for _, t := range tg.Tasks {
		if _, ok := referencedTaskIDs[t.Name]; ok && t.ShutdownDelay == 0 {
			warnings = append(warnings, fmt.Errorf(
				"group %q references task %q in a service definition, but the task has no shutdown_delay set",
				tg.Name, t.Name))
		}

		if t.ShutdownDelay > 0 {
			anyTaskHasShutdownDelay = true
		} else if len(t.Services) > 0 {
			warnings = append(warnings, fmt.Errorf(
				"task %q in group %q defines services, but has no shutdown_delay set",
				t.Name, tg.Name))
		}
	}

	if hasUnscopedGroupService && !hasGroupShutdownDelay && !anyTaskHasShutdownDelay {
		warnings = append(warnings, fmt.Errorf(
			"group %q defines services, but neither the group nor any of its tasks have shutdown_delay set", tg.Name))
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Set `shutdown_delay` on the referenced task in the group.
Or acknowledge the warning if connection draining is not a concern for that workload.
Re-run `nomad job validate` after edits to confirm the warning is gone.

Example fix

// before
task "app" { driver = "docker" }
// after
task "app" { driver = "docker"; shutdown_delay = "5s" }

Defensive patterns

Strategy: validation

Validate before calling

for _, t := range group.Tasks {
    if t.ShutdownDelay == 0 {
        log.Warnf("task %q referenced by services has no shutdown_delay", t.Name)
    }
}

Prevention

Set shutdown_delay on any task referenced by service definitions.
Review group service references when adding new tasks.
Check warning output of `nomad job run` after each spec change.

When it happens

Trigger: A group service (or connect sidecar) references a task by name, and the referenced task in tg.Tasks has ShutdownDelay == 0 at validation time. Surfaced through CLI warning formatting (Meta.FormatWarnings).

Common situations: Group-level connect sidecars referencing app tasks; tasks defined without a shutdown_delay while services point at them; specs copied from examples predating shutdown_delay defaults.

Related errors

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