hashicorp/nomad · error

can not target wildcard ("*")namespace

Error message

can not target wildcard ("*")namespace

What it means

errWildCardNamespace is the sentinel error "can not target wildcard (\"*\")namespace" in Nomad's structs package. ValidateForLock rejects any variable-decrypt request whose Namespace is AllNamespacesSentinel ("*"), because lock operations require targeting exactly one namespace; the wildcard is only meaningful for read-all queries.

Source

Thrown at nomad/structs/variables.go:74

	// 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
	CreateTime  int64
	ModifyIndex uint64

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the request's Namespace to a concrete namespace (e.g. "default") before performing the lock operation.
2. Derive the target namespace from the variable's own metadata instead of propagating the wildcard filter.
3. Change tooling defaults so lock operations never inherit a wildcard namespace scope.

Example fix

// before
vd.Namespace = structs.AllNamespacesSentinel // "*"
ValidateForLock(vd) // rejected
// after
vd.Namespace = "default"
ValidateForLock(vd)

if vd.Namespace == structs.AllNamespacesSentinel {
	return errors.New("lock operations require a concrete namespace, not \"*\"")
}

func lockableNamespace(ns string) bool { return ns != "" && ns != structs.AllNamespacesSentinel }

if errors.Is(err, structs.ErrWildCardNamespace) {
	// replace the wildcard namespace with a concrete one and retry
}

When it happens

Trigger: Calling ValidateForLock on a VariableDecrypted whose Namespace == "*" (AllNamespacesSentinel), e.g. lock/unlock requests issued with the wildcard namespace from a wildcard-capable read query.

Common situations: Reusing a list/query request (which allows namespace="*") as the basis for a lock operation; CLI or API clients inheriting the wildcard namespace from a global -namespace '*' setting; attempting cross-namespace lock acquisition.

Related errors

• missing namespace
• missing lock ID
• job_submission requires a namespace
• variable already holds a lock
• variable doesn't hold a lock

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