hashicorp/nomad · error

at least one policy should be specified

Error message

at least one policy should be specified

What it means

Appended by ACLRole.Validate when the role has no policy links (len(a.Policies) < 1); an ACL role is meaningless without at least one policy attached, so validation fails.

Source

Thrown at nomad/structs/acl.go:1022

}

// Validate ensure the ACL role contains valid information which meets Nomad's
// internal requirements. This does not include any state calls, such as
// ensuring the linked policies exist.
func (a *ACLRole) Validate() error {

	var mErr multierror.Error

	if !ValidACLRoleName.MatchString(a.Name) {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("invalid name '%s'", a.Name))
	}

	if len(a.Description) > maxACLRoleDescriptionLength {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("description longer than %d", maxACLRoleDescriptionLength))
	}

	if len(a.Policies) < 1 {
		mErr.Errors = append(mErr.Errors, errors.New("at least one policy should be specified"))
	}

	return mErr.ErrorOrNil()
}

// Canonicalize performs basic canonicalization on the ACL role object. It is
// important for callers to understand certain fields such as ID are set if it
// is empty, so copies should be taken if needed before calling this function.
func (a *ACLRole) Canonicalize() {
	if a.ID == "" {
		a.ID = uuid.Generate()
	}
}

// Equal performs an equality check on the two service registrations. It
// handles nil objects.
func (a *ACLRole) Equal(o *ACLRole) bool {
	if a == nil || o == nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add at least one policy (by name or ID) to the role's Policies field before submitting
2. Create the policy first, then the role referencing it
3. If a role genuinely has no permissions yet, delay creation until a policy is assigned

Example fix

// before
role := &api.ACLRole{Name: "reader", Policies: []*api.ACLRolePolicyLink{}}
// after
role := &api.ACLRole{Name: "reader", Policies: []*api.ACLRolePolicyLink{{Name: "read-only"}}}

func validRole(r *structs.ACLRole) error {
  if len(r.Policies) < 1 {
    return errors.New("ACL role requires at least one policy")
  }
  return nil
}

When it happens

Trigger: POSTing an ACL role with policies: [] or omitted to the ACL role create/update API (ACL.UpsertRoles / ACLRole.Validate).

Common situations: Creating a role via the Nomad API or nomad acl role create without attaching any policy; templating tools that render an empty policies list; refactors that moved policies into roles but left the list empty pending later assignment.

Related errors

• token name too long
• client token missing policies or roles
• management token cannot be associated with policies or roles
• token type must be client or management
• expiration time cannot be before create time

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