hashicorp/nomad · error

network hostname %q is not a valid DNS name

Error message

network hostname %q is not a valid DNS name

What it means

The network_hook's Prerun validates the (possibly interpolation-resolved) network hostname with dns.IsDomainName before using it to create the allocation network. Job registration validation can be bypassed when a hostname contains interpolation syntax, so the client re-validates and rejects hostnames that are not valid DNS names.

Source

Thrown at client/allocrunner/network_hook.go:132

	tg := h.alloc.Job.LookupTaskGroup(h.alloc.TaskGroup)
	if len(tg.Networks) == 0 || tg.Networks[0].Mode == "host" || tg.Networks[0].Mode == "" {
		return nil
	}

	if h.manager == nil || h.networkConfigurator == nil {
		h.logger.Trace("shared network namespaces are not supported on this platform, skipping network hook")
		return nil
	}

	// Perform our networks block interpolation.
	interpolatedNetworks := taskenv.InterpolateNetworks(allocEnv, tg.Networks)

	// Interpolated values need to be validated. It is also possible a user
	// supplied hostname avoids the validation on job registrations because it
	// looks like it includes interpolation, when it doesn't.
	if interpolatedNetworks[0].Hostname != "" {
		if _, ok := dns.IsDomainName(interpolatedNetworks[0].Hostname); !ok {
			return fmt.Errorf("network hostname %q is not a valid DNS name", interpolatedNetworks[0].Hostname)
		}
	}

	// Our network create request.
	networkCreateReq := drivers.NetworkCreateRequest{
		Hostname: interpolatedNetworks[0].Hostname,
	}

	var checkedOnce bool

CREATE:
	spec, created, err := h.manager.CreateNetwork(h.alloc.ID, &networkCreateReq)
	if err != nil {
		return fmt.Errorf("failed to create network for alloc: %v", err)
	}

	if spec != nil {
		h.spec = spec

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Change the group network hostname in the jobspec to a valid DNS label/domain name (letters, digits, hyphens, dot-separated).
2. If using interpolation, choose a node/job attribute that resolves to a DNS-safe value or wrap/sanitize it (e.g. use node.unique.id instead of names with underscores).
3. Run `nomad job validate` to catch interpolation/validation issues before submitting.
4. Re-run the job after fixing; the client caches nothing for this check so the next Prerun validates the new value.

Example fix

// before
network {
  mode = "bridge"
  hostname = "${node.unique.name}" // may contain underscores/invalid chars
}

// after
network {
  mode = "bridge"
  hostname = "my-app-1" // valid DNS name
}

import "github.com/miekg/dns"
func isValidDNSName(name string) bool {
    return name != "" && dns.IsDomainName(name) && !strings.Contains(name, "${")
}

func hostnameSafe(h string) bool {
    if h == "" || strings.Contains(h, "$") { return h == "" }
    return dns.IsDomainName(h)
}

if err := hook.Prerun(); err != nil && strings.Contains(err.Error(), "is not a valid DNS name") {
    // fix the jobspec hostname and resubmit
}

When it happens

Trigger: networks[0].Hostname is non-empty after interpolation and dns.IsDomainName returns false — e.g. hostname contains invalid characters, underscores, spaces, or failed interpolation leaving a literal placeholder like "${node.unique.name}".

Common situations: Users set group network hostname to a value with illegal DNS characters, or use node/job interpolation that resolves to a name with invalid characters (dots in wrong places, empty segments), or leave an uninterpolated ${...} string because the attribute doesn't exist.

Related errors

• hostname cannot be set on task group using %q networking mod
• Failed to resolve Server RPC advertise address: %v
• error parsing reserved_ports: %w
• error parsing reserved_ports for network %q: %w
• network address family must be one of: "", %q, %q

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