What causes "empty variables are invalid" in hashicorp/nomad?

Include at least one key/value pair in Items before saving.

empty variables are invalid

Error message

empty variables are invalid

What it means

VariableDecrypted.Validate rejects variables whose Items map is empty. A variable must carry at least one key/value pair; an empty payload is considered invalid because it cannot represent meaningful variable data and would leave an unusable raft entry. This is a distinct inline errors.New at nomad/structs/variables.go:375.

Source

Thrown at nomad/structs/variables.go:375

}

var (
	// validVariablePath is used to validate a variable path. We restrict to
	// RFC3986 URL-safe characters that don't conflict with the use of
	// characters "@" and "." in template blocks. We also restrict the length so
	// that a user can't make queries in the state store unusually expensive (as
	// they are O(k) on the key length)
	validVariablePath = regexp.MustCompile("^[a-zA-Z0-9-_~/]{1,128}$")
)

func (vd VariableDecrypted) Validate() error {

	if vd.Namespace == AllNamespacesSentinel {
		return errors.New("can not target wildcard (\"*\")namespace")
	}

	if len(vd.Items) == 0 {
		return errors.New("empty variables are invalid")
	}

	if vd.Items.Size() > maxVariableSize {
		return errors.New("variables are limited to 64KiB in total size")
	}

	if err := ValidatePath(vd.Path); err != nil {
		return err
	}

	if vd.Lock != nil {
		return vd.Lock.Validate()
	}

	return nil
}

// ValidateForLock ensures a new variable can be created just to support a lock,

View on GitHub (pinned to 482b49bf1a)

Solutions

Include at least one key/value pair in Items before saving.
If you intend to remove the variable, use the variable delete API instead of writing an empty variable.
Validate Items length client-side and fail fast with a clear message when empty.

Example fix

// before
v := &structs.VariableDecrypted{Namespace: "default", Path: "app/config", Items: map[string]string{}}
// after
v := &structs.VariableDecrypted{Namespace: "default", Path: "app/config", Items: map[string]string{"key": "value"}}
// or, to remove: use the DELETE variable API, not an empty put

Defensive patterns

Strategy: validation

Validate before calling

func hasItems(v structs.VariableDecrypted) bool {
	return len(v.Items) > 0
}

Try / catch

if err := v.Validate(); err != nil {
	if strings.Contains(err.Error(), "empty variables are invalid") {
		return fmt.Errorf("variable %q has no items; add key=value pairs or delete the variable instead", v.Path)
	}
	return err
}

Prevention

Check len(Items) > 0 before put operations.
Use the delete API to remove variables rather than writing empty ones.
Fail fast in scripts when rendered item sets come out empty.

When it happens

Trigger: Calling Validate on a VariableDecrypted with nil or zero-length Items map; e.g. nomad var put with no key=value arguments, or a template that renders an empty item set.

Common situations: Scripted variable writes where all keys were filtered out; deleting the last key by putting an empty set instead of using the delete API; JSON payloads with an empty "Items" or "VariableKVDict" object.

Related errors

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