hashicorp/nomad · error

errMissingACLRoleID

errMissingACLRoleID

Error message

missing ACL role ID

What it means

errMissingACLRoleID is a shared sentinel error used by ACLRoles.Update, Delete, and Get when the required ACL role ID parameter (role.ID or roleID) is an empty string. The call is rejected locally before any HTTP request, because the role ID is part of the request path (/v1/acl/role/<id>).

Source

Thrown at api/acl.go:245

	if secret == "" {
		return nil, nil, errors.New("missing secret ID")
	}
	req := &OneTimeTokenExchangeRequest{OneTimeSecretID: secret}
	var resp *OneTimeTokenExchangeResponse
	wm, err := a.client.put("/v1/acl/token/onetime/exchange", req, &resp, q)
	if err != nil {
		return nil, nil, err
	}
	if resp == nil {
		return nil, nil, errors.New("no ACL token returned")
	}
	return resp.Token, wm, nil
}

var (
	// errMissingACLRoleID is the generic errors to use when a call is missing
	// the required ACL Role ID parameter.
	errMissingACLRoleID = errors.New("missing ACL role ID")

	// errMissingACLAuthMethodName is the generic error to use when a call is
	// missing the required ACL auth-method name parameter.
	errMissingACLAuthMethodName = errors.New("missing ACL auth-method name")

	// errMissingACLBindingRuleID is the generic error to use when a call is
	// missing the required ACL binding rule ID parameter.
	errMissingACLBindingRuleID = errors.New("missing ACL binding rule ID")
)

// ACLRoles is used to query the ACL Role endpoints.
type ACLRoles struct {
	client *Client
}

// ACLRoles returns a new handle on the ACL roles API client.
func (c *Client) ACLRoles() *ACLRoles {
	return &ACLRoles{client: c}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set role.ID to the role's UUID before calling Update (fetch it via ACLRoles.GetByName or List if unknown).
2. Pass the actual role ID (UUID), not the name, to Delete/Get; use GetByName for name-based lookup.
3. Validate the ID is non-empty in your caller before invoking these methods.

Example fix

// before
_, _, err := client.ACL().Roles().Update(&api.ACLRole{Name: "my-role"}, nil)
// after
role, _, err := client.ACL().Roles().GetByName("my-role", nil)
if err != nil {
    return err
}
role.Description = "updated"
_, _, err = client.ACL().Roles().Update(role, nil)

if role == nil || role.ID == "" {
    return fmt.Errorf("ACL role ID is required for update/delete/get")
}

func hasRoleID(r *api.ACLRole) bool { return r != nil && r.ID != "" }

When it happens

Trigger: ACLRoles.Update(role) with role.ID == ""; ACLRoles.Delete(""); ACLRoles.Get("") — i.e. any role-management call whose ID argument is unset.

Common situations: Constructing an ACLRole struct for update but forgetting to set ID (only setting Name); reading a role ID from a CLI flag/env var that is empty; passing the role Name where the ID is required.

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

• errMissingACLAuthMethodName
• errMissingACLBindingRuleID
• missing ACL role name
• 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/c7acab0ab9fe1384. Report an issue: GitHub.