hashicorp/nomad · error

Invalid agent policy: %#v

Error message

Invalid agent policy: %#v

What it means

acl.Parse (acl/policy.go:679) validates the top-level agent block's Policy string with isPolicyValid, which only accepts deny, read, write, scale. An agent block with any other policy value (including 'list', which is valid for plugins but not agent) fails parsing and rejects the whole policy.

Source

Thrown at acl/policy.go:679

		// Remove the host-volume name from the extra key list.
		p.removeExtraKey(hv.Name)
	}

	// Now that we have processed all known keys, return an error if the
	// operator wrote a policy with unknown keys if we are being strict. While
	// these do not grant any extra privileges, it can be misleaing to allow
	// these and cause problems later if we add new capabilities that collide
	// with the unknown keys.
	if len(p.ExtraKeysHCL) > 0 && strict {
		return nil, fmt.Errorf("Invalid or duplicate policy keys: %v",
			strings.Join(p.ExtraKeysHCL, ", "))
	}

	p.ExtraKeysHCL = nil

	if p.Agent != nil && !isPolicyValid(p.Agent.Policy) {
		return nil, fmt.Errorf("Invalid agent policy: %#v", p.Agent)
	}

	if p.Node != nil && !isPolicyValid(p.Node.Policy) {
		return nil, fmt.Errorf("Invalid node policy: %#v", p.Node)
	}

	if p.Operator != nil {
		if p.Operator.Policy != "" && !isPolicyValid(p.Operator.Policy) {
			return nil, fmt.Errorf("Invalid operator policy: %#v", p.Operator)
		}
		for _, cap := range p.Operator.Capabilities {
			if !isOperatorCapabilityValid(cap) {
				return nil, fmt.Errorf("Invalid operator capability '%s'", cap)
			}
		}

		// Expand the short hand policy to the capabilities and
		// add to any existing capabilities

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the agent block's policy to exactly one of: deny, read, write, scale (lowercase).
2. Use capabilities for fine-grained agent permissions instead of the shorthand if the needed level is not expressible.
3. Inspect the %#v struct in the error to confirm it is the agent block and see the current Policy value.

Example fix

// before
agent {
  policy = "list"
}
// after
agent {
  policy = "read"
}

if policy.Agent != nil && policy.Agent.Policy != "" &&
    !map[string]bool{"deny": true, "read": true, "write": true, "scale": true}[policy.Agent.Policy] {
    return fmt.Errorf("agent policy %q must be deny|read|write|scale", policy.Agent.Policy)
}

func isPolicyValid(policy string) bool {
    switch policy {
    case "deny", "read", "write", "scale":
        return true
    }
    return false
}

_, err := acl.Parse(rules, acl.PolicyParseStrict)
if err != nil {
    if strings.Contains(err.Error(), "Invalid agent policy") {
        // correct the agent block's policy to a valid shorthand
    }
    return err
}

When it happens

Trigger: acl.Parse on a policy containing agent { policy = "<invalid>" } where the value is not exactly "deny", "read", "write", or "scale" — e.g. 'list', 'Read', 'monitor', or an empty-but-set string from a template.

Common situations: Copying the plugin block's allowed 'list' policy into the agent block; capitalization mistakes; automated policy generation substituting a capability name where a policy shorthand is expected.

Related errors

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

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