hashicorp/nomad · error

auth method is missing

Error message

auth method is missing

What it means

An ACLBindingRule must reference the ACL auth method it belongs to. ACLBindingRule.Validate() appends this error to its multierror when AuthMethod is the empty string, because a binding rule without an auth method can never be evaluated during login.

Source

Thrown at nomad/structs/acl.go:2087

	// therefore we need to generate base information.
	if a.ID == "" {
		a.ID = uuid.Generate()
		a.CreateTime = now
	}

	// The fact this function is being called indicates we are attempting an
	// upsert into state. Therefore, update the modify time.
	a.ModifyTime = now
}

// Validate ensures the ACL binding rule contains valid information which meets
// Nomad's internal requirements.
func (a *ACLBindingRule) Validate() error {

	var mErr multierror.Error

	if a.AuthMethod == "" {
		mErr.Errors = append(mErr.Errors, errors.New("auth method is missing"))
	}
	if len(a.Description) > maxACLBindingRuleDescriptionLength {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("description longer than %d", maxACLRoleDescriptionLength))
	}

	// Depending on the bind type, we have some specific validation. Catching
	// the empty string also provides easier to understand feedback to the
	// user.
	switch a.BindType {
	case "":
		mErr.Errors = append(mErr.Errors, errors.New("bind type is missing"))
	case ACLBindingRuleBindTypeRole, ACLBindingRuleBindTypePolicy:
		if a.BindName == "" {
			mErr.Errors = append(mErr.Errors, errors.New("bind name is missing"))
		}
	case ACLBindingRuleBindTypeManagement:
		if a.BindName != "" {
			mErr.Errors = append(mErr.Errors, errors.New("bind name should be empty"))

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set AuthMethod to the name of an existing ACL auth method before submitting
2. Create the auth method first (nomad acl auth-method create) then reference its exact name
3. Check CLI/API payloads include auth_method

Example fix

// before
rule := &structs.ACLBindingRule{
  BindType: structs.ACLBindingRuleBindTypePolicy,
  BindName: "eng-dev",
}
// after
rule := &structs.ACLBindingRule{
  AuthMethod: "okoidc",
  BindType: structs.ACLBindingRuleBindTypePolicy,
  BindName: "eng-dev",
}

if rule.AuthMethod == "" {
    return errors.New("binding rule requires AuthMethod")
}
if err := rule.Validate(); err != nil { return err }

if err := rule.Validate(); err != nil {
    if strings.Contains(err.Error(), "auth method is missing") {
        // populate rule.AuthMethod and resubmit
    }
    return err
}

When it happens

Trigger: Creating or updating a binding rule via the ACL API/CLI/nomad acl binding-rule create with no AuthMethod field set.

Common situations: Hand-written JSON payloads omitting auth_method; SDK usage constructing ACLBindingRule structs directly; CLI flags forgotten (e.g. missing -method); imports from other systems where the field was named differently.

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

• bind type is missing
• bind name is missing
• bind name should be empty
• ACL auth method lookup failed: %v
• ACL binding rule insert failed: ACL auth method not found

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