hashicorp/nomad · error

Invalid namespace capability '%s': %#v

Error message

Invalid namespace capability '%s': %#v

What it means

Returned by acl.Parse in acl/policy.go:578 when a namespace stanza lists a capability not accepted by isNamespaceCapabilityValid (acl/policy.go:281). Valid capabilities include list-jobs, read-job, submit-job, dispatch-job, read-logs, alloc-exec, csi-* volume capabilities, host-volume-* capabilities, scaling/deployment capabilities, sentinel-override and submit-recommendation (enterprise). Any other string is rejected.

Source

Thrown at acl/policy.go:578

	}

	// At least one valid policy must be specified, we don't want to store only
	// raw data
	if p.IsEmpty() {
		return nil, fmt.Errorf("Invalid policy: %s", p.Raw)
	}

	// Validate the policy
	for _, ns := range p.Namespaces {
		if !validNamespace.MatchString(ns.Name) {
			return nil, fmt.Errorf("Invalid namespace name: %#v", ns)
		}
		if ns.Policy != "" && !isPolicyValid(ns.Policy) {
			return nil, fmt.Errorf("Invalid namespace policy: %#v", ns)
		}
		for _, cap := range ns.Capabilities {
			if !isNamespaceCapabilityValid(cap) {
				return nil, fmt.Errorf("Invalid namespace capability '%s': %#v", cap, ns)
			}
		}

		// Expand the short hand policy to the capabilities and
		// add to any existing capabilities
		if ns.Policy != "" {
			extraCap := expandNamespacePolicy(ns.Policy)
			ns.Capabilities = append(ns.Capabilities, extraCap...)
		}

		// Expand implicit capabilities
		expandNamespaceCapabilities(ns)

		if ns.Variables != nil {
			if len(ns.Variables.Paths) == 0 {
				return nil, fmt.Errorf("Invalid variable policy: no variable paths in namespace %s", ns.Name)
			}
			for _, pathPolicy := range ns.Variables.Paths {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Replace the capability with one from Nomad's documented namespace capability list (exact kebab-case spelling)
2. Move non-namespace capabilities (e.g. node-pool or variables capabilities) into their own stanzas
3. Upgrade the nomad dependency if the capability exists in a newer Nomad release
4. Use short-hand policy = "read"/"write" instead of hand-listed capabilities when possible

Example fix

// before
namespace "prod" {
  capabilities = ["read-jobs", "submit-job"]
}
// after
namespace "prod" {
  capabilities = ["read-job", "submit-job"]
}

var validNsCaps = map[string]bool{
  "deny":true,"list-jobs":true,"parse-job":true,"read-job":true,"submit-job":true,
  "dispatch-job":true,"read-logs":true,"read-fs":true,"alloc-exec":true,"alloc-node-exec":true,
  "alloc-lifecycle":true,"csi-register-plugin":true,"csi-write-volume":true,"csi-read-volume":true,
  "csi-list-volume":true,"csi-mount-volume":true,"host-volume-create":true,"host-volume-register":true,
  "host-volume-read":true,"host-volume-write":true,"host-volume-delete":true,
  "list-scaling-policies":true,"read-scaling-policy":true,"read-job-scaling":true,"scale-job":true,
  "register-job":true,"revert-job":true,"deregister-job":true,"purge-job":true,"evaluate-job":true,
  "plan-job":true,"tag-job-version":true,"stable-job":true,"fail-deployment":true,"pause-deployment":true,
  "promote-deployment":true,"unblock-deployment":true,"cancel-deployment":true,"set-alloc-health":true,
  "gc-alloc":true,"pause-alloc":true,"force-periodic-job":true,"delete-service-registration":true,
  "sentinel-override":true,"submit-recommendation":true,
}
for _, ns := range policy.Namespaces {
  for _, c := range ns.Capabilities {
    if !validNsCaps[c] { return fmt.Errorf("namespace %s: bad capability %q", ns.Name, c) }
  }
}

When it happens

Trigger: Calling acl.Parse with namespace { capabilities = [...] } containing an unknown/misspelled capability string, a node-pool or variables capability misplaced in a namespace stanza, or an operator capability like 'snapshot-save' inside capabilities.

Common situations: Typos ('submit-jobs', 'read-fs' vs 'read-fs' correct form is 'read-fs'? actually list-fs variants) — most often hyphen/singular-plural mistakes; copying capabilities between stanza types (node_pool vs namespace vs variables); using capabilities from a newer Nomad release against an older vendored library version that lacks them.

Related errors

• Invalid namespace name: %#v
• Invalid namespace policy: %#v
• Invalid variable policy: no variable paths in namespace %s
• Invalid missing variable path in namespace %s
• Invalid variable capability '%s' in namespace %s

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