What causes "missing required Meta object" in hashicorp/nomad?

Populate request.Meta with at least one key/value pair before submitting.

missing required Meta object

Error message

missing required Meta object

What it means

NodeMetaApplyRequest.Validate enforces that a node metadata update actually carries a Meta map; an empty map (len == 0) is rejected with "missing required Meta object". Nomad requires at least one key so an update request can't be a no-op or an accidental wipe via empty payload.

Source

Thrown at nomad/structs/node.go:496

	ScheduleState TaskScheduleState
}

// NodeMetaApplyRequest is used to update Node metadata on Client agents.
type NodeMetaApplyRequest struct {
	QueryOptions // Client RPCs must use QueryOptions to set AllowStale=true

	// NodeID is the node being targeted by this request (or the node
	// receiving this request if NodeID is empty).
	NodeID string

	// Meta is the new Node metadata being applied and differs slightly
	// 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
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Populate request.Meta with at least one key/value pair before submitting.
Check upstream inputs: if nothing changed, skip the API call instead of sending an empty request.
For deleting keys, include them with nil values rather than sending an empty map.

Example fix

// before
req := &structs.NodeMetaApplyRequest{Meta: map[string]*string{}}
// after
req := &structs.NodeMetaApplyRequest{Meta: map[string]*string{"env": strPtr("prod")}}

Defensive patterns

Strategy: validation

Validate before calling

func validateMetaReq(req *structs.NodeMetaApplyRequest) error {
  if req == nil || len(req.Meta) == 0 {
    return errors.New("node meta update requires at least one key")
  }
  return nil
}

Type guard

func hasMeta(m map[string]*string) bool { return len(m) > 0 }

Try / catch

null

Prevention

Skip the update call entirely when the computed diff is empty
Represent deletions as keys with nil values, never an empty map
Unit-test automation that builds NodeMetaApplyRequest payloads

When it happens

Trigger: Calling the node metadata update API (e.g. Client().Nodes().UpdateMeta) with a NodeMetaApplyRequest whose Meta map is nil or empty.

Common situations: Script building the request from an empty env/config map; CLI/API client serializing no changes; accidental omission of meta flags in automation.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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