hashicorp/nomad · error

network address family must be one of: "", %q, %q

Error message

network address family must be one of: "", %q, %q

What it means

NodeNetworkAF.Validate() checks that a node's advertised network address family is one of the three legal values: empty string (unset), NodeNetworkAF_IPv4, or NodeNetworkAF_IPv6. Any other string in the NodeNetworkAF field of node network resources fails validation.

Source

Thrown at nomad/structs/structs.go:2740

			return true
		}
	}
	return false
}

type NodeNetworkAF string

const (
	NodeNetworkAF_IPv4 NodeNetworkAF = "ipv4"
	NodeNetworkAF_IPv6 NodeNetworkAF = "ipv6"
)

// Validate validates that NodeNetworkAF has a legal value.
func (n NodeNetworkAF) Validate() error {
	if n == "" || n == NodeNetworkAF_IPv4 || n == NodeNetworkAF_IPv6 {
		return nil
	}
	return fmt.Errorf(`network address family must be one of: "", %q, %q`, NodeNetworkAF_IPv4, NodeNetworkAF_IPv6)
}

type NodeNetworkAddress struct {
	Family        NodeNetworkAF
	Alias         string
	Address       string
	ReservedPorts string
	Gateway       string // default route for this address
}

type AllocatedPortMapping struct {
	// msgpack omit empty fields during serialization
	_struct bool `codec:",omitempty"` // nolint: structcheck

	Label           string
	Value           int
	To              int
	HostIP          string

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the family to exactly NodeNetworkAF_IPv4 ("ipv4") or NodeNetworkAF_IPv6 ("ipv6") as defined by the constants
2. Leave the field as the empty string if the family is unknown/unset
3. Fix the fingerprint/plugin or payload generator to emit the canonical constant

Example fix

// before
n.Family = "IPV4"
// after
n.Family = structs.NodeNetworkAF_IPv4 // "ipv4"

switch fam {
case "", structs.NodeNetworkAF_IPv4, structs.NodeNetworkAF_IPv6:
    // ok
default:
    return fmt.Errorf("invalid network address family: %q", fam)
}

func validNodeNetworkAF(n structs.NodeNetworkAF) bool {
    return n == "" || n == structs.NodeNetworkAF_IPv4 || n == structs.NodeNetworkAF_IPv6
}

When it happens

Trigger: Client configuration or a plugin setting NodeNetworkAF to an arbitrary string like "ipv4" (wrong case) or "dual-stack" instead of the exact enum constants; fingerprint code producing unexpected family values.

Common situations: Custom node fingerprint plugins emitting non-constant family strings; hand-crafted node registration payloads in tests or via the API; case sensitivity mistakes (IPv4 vs ipv4).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Must provide the NodeID
• not a valid task schedule state
• numa affinity must be one of none, prefer, or require
• Invalid change mode. Must be one of the following: noop, sig
• http addr of node %q (%s) is not advertised

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