hashicorp/nomad · error

%q is invalid; metadata keys must be valid dotted hcl identi

Error message

%q is invalid; metadata keys must be valid dotted hcl identifiers

What it means

NodeMetaApplyRequest.Validate found a metadata key that is not a valid dotted HCL identifier (each dot-separated part must match hclsyntax identifier rules); keys are interpolated as HCL variables in constraints.

Source

Thrown at nomad/structs/node.go:508

	// from Node.Meta as nil values are used to unset Node.Meta keys.
	Meta map[string]*string
}

func (n *NodeMetaApplyRequest) Validate() error {
	if len(n.Meta) == 0 {
		return fmt.Errorf("missing required Meta object")
	}
	for k := range n.Meta {
		if k == "" {
			return fmt.Errorf("metadata keys must not be empty")
		}

		// Validate keys are dotted identifiers since their primary use case is in
		// constraints as interpolated hcl variables.
		// https://github.com/hashicorp/hcl/blob/v2.16.0/hclsyntax/spec.md#identifiers
		for part := range strings.SplitSeq(k, ".") {
			if !hclsyntax.ValidIdentifier(part) {
				return fmt.Errorf("%q is invalid; metadata keys must be valid dotted hcl identifiers", k)
			}
		}
	}

	return nil
}

// NodeMetaResponse is used to read Node metadata directly from Client agents.
type NodeMetaResponse struct {
	// Meta is the merged static + dynamic Node metadata
	Meta map[string]string

	// Dynamic is the dynamic Node metadata (set via API)
	Dynamic map[string]*string

	// Static is the static Node metadata (set via agent configuration)
	Static map[string]string
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use only letters, digits, hyphens, underscores and dots in metadata keys
2. Remove invalid characters or leading/trailing dots from the key

When it happens

Trigger: Thrown at nomad/structs/node.go:508 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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