hashicorp/nomad · error

missing namespace

Error message

missing namespace

What it means

errNoNamespace is the sentinel error "missing namespace" in Nomad's structs package. Every variable lives in a namespace, and validation expects Namespace to be set (Canonicalize normally fills it with "default"); an empty namespace after canonicalization means the request was malformed and is rejected.

Source

Thrown at nomad/structs/variables.go:72

	// minVariableLockTTL and maxVariableLockTTL determine the range of valid durations for the
	// TTL on a lock.They come from the experience on Consul.
	minVariableLockTTL = 10 * time.Second
	maxVariableLockTTL = 24 * time.Hour

	// defaultLockTTL is the default value used to maintain a lock before it needs to
	// be renewed. The actual value comes from the experience with Consul.
	defaultLockTTL = 15 * time.Second

	// defaultLockDelay is the default a lock will be blocked after the TTL
	// went by without any renews. It is intended to prevent split brain situations.
	// The actual value comes from the experience with Consul.
	defaultLockDelay = 15 * time.Second
)

var (
	errNoPath             = errors.New("missing path")
	errNoNamespace        = errors.New("missing namespace")
	errNoLock             = errors.New("missing lock ID")
	errWildCardNamespace  = errors.New("can not target wildcard (\"*\")namespace")
	errQuotaExhausted     = errors.New("variables are limited to 64KiB in total size")
	errNegativeDelayOrTTL = errors.New("Lock delay and TTL must be positive")
	errInvalidTTL         = errors.New("TTL must be between 10 seconds and 24 hours")
)

// VariableMetadata is the metadata envelope for a Variable, it is the list
// object and is shared data between an VariableEncrypted and a
// VariableDecrypted object.
type VariableMetadata struct {
	Namespace string
	Path      string

	// Lock represents a variable which is used for locking functionality.
	Lock *VariableLock `json:",omitempty"`

	CreateIndex uint64

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set Namespace explicitly in the variable payload (e.g. "default") before submitting.
2. Call Canonicalize() on the Variable struct before Validate so the namespace is defaulted.
3. If using the CLI, ensure the -namespace flag or namespace context is set appropriately.

Example fix

// before
v := &structs.Variable{Path: "a/b"}
// after
v := &structs.Variable{Path: "a/b", Namespace: "default"}

if v.Namespace == "" {
	v.Namespace = "default"
}

func hasNamespace(v *structs.Variable) bool { return v != nil && v.Namespace != "" }

if errors.Is(err, structs.ErrNoNamespace) {
	v.Canonicalize() // defaults namespace
	err = v.Validate()
}

When it happens

Trigger: Submitting a variable payload whose Namespace field is the empty string and bypassing or preceding canonicalization; constructing structs.Variable or VariableDecrypted in code/tests without setting Namespace before Validate.

Common situations: Raw API calls to /v1/var omitting the Namespace field; SDK/tooling that copies only path and items; hitting the validation path before Canonicalize() has had a chance to default the namespace.

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

• can not target wildcard ("*")namespace
• job_submission requires a namespace
• Job must be in a namespace
• missing path
• missing lock ID

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