What causes "missing ACL role name" in hashicorp/nomad?

Pass the correct role name to GetByName (list roles via ACLRoles.List if the name is unknown).

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.

Solutions

Pass the correct role name to GetByName (list roles via ACLRoles.List if the name is unknown).
Check the config/env source of the role name for missing or misnamed keys.
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)

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Validate config keys for role names at startup.
Prefer resolving roles once at boot and caching their IDs rather than repeated name lookups.

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

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

Appendix: 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)