hashicorp/nomad · error

hostname cannot be set on task group using %q networking mod

Error message

hostname cannot be set on task group using %q networking mode

What it means

newNetworkManager builds the client's network manager for a task group. Setting a hostname is only supported when the group's networking mode maps to the 'group' isolation mode (bridge or none). If the group declares a hostname while using another mode (e.g. host), construction fails with this error before any network is created.

Source

Thrown at client/allocrunner/network_manager_linux.go:38

func newNetworkManager(alloc *structs.Allocation, driverManager drivermanager.Manager) (nm drivers.DriverNetworkManager, err error) {
	// The defaultNetworkManager is used if a driver doesn't need to create the network
	nm = &defaultNetworkManager{}
	tg := alloc.Job.LookupTaskGroup(alloc.TaskGroup)

	// default netmode to host, this can be overridden by the task or task group
	tgNetMode := "host"
	if len(tg.Networks) > 0 && tg.Networks[0].Mode != "" {
		tgNetMode = tg.Networks[0].Mode
	}

	groupIsolationMode := netModeToIsolationMode(tgNetMode)

	// Setting the hostname is only possible where the task groups networking
	// mode is group; meaning bridge or none.
	if len(tg.Networks) > 0 &&
		(groupIsolationMode != drivers.NetIsolationModeGroup && tg.Networks[0].Hostname != "") {
		return nil, fmt.Errorf("hostname cannot be set on task group using %q networking mode",
			groupIsolationMode)
	}

	// networkInitiator tracks the task driver which needs to create the network
	// to check for multiple drivers needing to create the network.
	var networkInitiator string

	// driverCaps tracks which drivers we've checked capabilities for so as not
	// to do extra work
	driverCaps := make(map[string]struct{})
	for _, task := range tg.Tasks {
		// the task's netmode defaults to the task group but can be overridden
		taskNetMode := tgNetMode
		if len(task.Resources.Networks) > 0 && task.Resources.Networks[0].Mode != "" {
			taskNetMode = task.Resources.Networks[0].Mode
		}

		// netmode host should always work to support backwards compat

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the hostname field from the network block, or
2. Switch the group network mode to "bridge" (or "none") where hostname is supported.
3. Validate the jobspec with `nomad job validate` before submission to catch the mismatch.
4. If a static name is needed on host networking, set it inside the container via the task driver's own hostname option instead.

Example fix

// before
network {
  mode = "host"
  hostname = "my-app" // not allowed in host mode
}

// after
network {
  mode = "bridge"
  hostname = "my-app"
}

func hostnameAllowed(mode string, hostname string) error {
    if hostname != "" && mode != "bridge" && mode != "none" {
        return fmt.Errorf("hostname cannot be set on network mode %q", mode)
    }
    return nil
}

func hostnameValidForMode(mode, hostname string) bool {
    return hostname == "" || mode == "bridge" || mode == "none"
}

When it happens

Trigger: tg.Networks is non-empty, tg.Networks[0].Hostname != "", and netModeToIsolationMode(tgNetMode) is not drivers.NetIsolationModeGroup — typically network { mode = "host" } combined with a hostname field.

Common situations: Users copy a jobspec from a bridge-mode example but switch mode to "host" while leaving hostname set; adding hostname to a task-level or host-mode network block; version upgrades where hostname validation got stricter.

Related errors

• network hostname %q is not a valid DNS name
• <combined HCL diagnostics from str.String()>
• command cannot be empty
• error parsing reserved_ports: %w
• error parsing reserved_ports for network %q: %w

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