hashicorp/nomad · error

missing ACL role name

Error message

missing ACL role name

What it means

ACLRoles.GetByName() looks up an ACL role by name via /v1/acl/role/name/<name>. Since the name is embedded in the request path, an empty name yields an invalid URL, so the client rejects the call locally before issuing the request.

Source

Thrown at api/acl.go:330

}

// Get is used to look up an ACL role.
func (a *ACLRoles) Get(roleID string, q *QueryOptions) (*ACLRole, *QueryMeta, error) {
	if roleID == "" {
		return nil, nil, errMissingACLRoleID
	}
	var resp ACLRole
	qm, err := a.client.query("/v1/acl/role/"+roleID, &resp, q)
	if err != nil {
		return nil, nil, err
	}
	return &resp, qm, nil
}

// GetByName is used to look up an ACL role using its name.
func (a *ACLRoles) GetByName(roleName string, q *QueryOptions) (*ACLRole, *QueryMeta, error) {
	if roleName == "" {
		return nil, nil, errors.New("missing ACL role name")
	}
	var resp ACLRole
	qm, err := a.client.query("/v1/acl/role/name/"+roleName, &resp, q)
	if err != nil {
		return nil, nil, err
	}
	return &resp, qm, nil
}

// ACLAuthMethods is used to query the ACL auth-methods endpoints.
type ACLAuthMethods struct {
	client *Client
}

// ACLAuthMethods returns a new handle on the ACL auth-methods API client.
func (c *Client) ACLAuthMethods() *ACLAuthMethods {
	return &ACLAuthMethods{client: c}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pass the correct role name to GetByName (list roles via ACLRoles.List if the name is unknown).
2. Check the config/env source of the role name for missing or misnamed keys.
3. Validate the name is non-empty in your caller before invoking GetByName.

Example fix

// before
role, _, err := client.ACL().Roles().GetByName(cfg.RoleName, nil)
// after
if cfg.RoleName == "" {
    return fmt.Errorf("role name must be configured")
}
role, _, err := client.ACL().Roles().GetByName(cfg.RoleName, nil)

if roleName == "" {
    return fmt.Errorf("ACL role name must be non-empty")
}

When it happens

Trigger: Calling ACLRoles.GetByName("") — typically the name came from an empty env var, missing config key, or an unset struct field.

Common situations: Config-driven role lookups where the role name key is missing in HCL/YAML; a CLI flag not supplied; chaining from a previous call that returned an empty name.

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

• errMissingACLRoleID
• errMissingACLAuthMethodName
• errMissingACLBindingRuleID
• cannot specify ACL role ID
• no one-time token returned

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