hashicorp/nomad · error

bind name should be empty

Error message

bind name should be empty

What it means

ACLBindingRule.Validate enforces that a bind rule of type 'management' carries an empty BindName, because management tokens are not bound to any specific policy or role. When BindName is set on a management-typed rule, Validate appends 'bind name should be empty' to its multierror. It is a configuration schema error for Nomad ACL binding rules.

Source

Thrown at nomad/structs/acl.go:2105

		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"))
		}
	default:
		mErr.Errors = append(mErr.Errors, fmt.Errorf("unsupported bind type: %q", a.BindType))
	}

	// If there is a selector configured, ensure that go-bexpr can parse this.
	// Otherwise, the user will get an ambiguous failure when attempting to
	// login.
	if a.Selector != "" {
		if _, err := bexpr.CreateEvaluator(a.Selector, nil); err != nil {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("selector is invalid: %v", err))
		}
	}

	return mErr.ErrorOrNil()
}

// Merge merges binding rule a with b. It sets all required empty fields of rule

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set BindName to "" when BindType is ACLBindingRuleBindTypeManagement
2. If a specific role/policy is intended, keep BindType as 'role' or 'policy' instead of 'management'
3. Remove stale bind_name fields from IaC/JSON templates for management rules
4. Fix the payload client-side before calling acl binding-rule create/update

Example fix

// before
rule := &structs.ACLBindingRule{
  BindType: structs.ACLBindingRuleBindTypeManagement,
  BindName: "admin-role",
}
// after
rule := &structs.ACLBindingRule{
  BindType: structs.ACLBindingRuleBindTypeManagement,
  BindName: "",
}

if rule.BindType == structs.ACLBindingRuleBindTypeManagement && rule.BindName != "" { return errors.New("BindName must be empty for management binding rules") }

When it happens

Trigger: Calling ACL Binding Rule Create/Update (ACLBindingRule with BindType "management") via the Nomad API or CLI while BindName is non-empty. E.g. copying a role-bound rule and only changing BindType to 'management' without clearing BindName.

Common situations: Operators editing binding rules via 'nomad acl binding-rule update' or Terraform/IaC that populates bind_name unconditionally; migrating rules from 'role'/'policy' types to 'management'; hand-written JSON payloads that leave bind_name filled.

Related errors

• unsupported bind type: %q
• selector is invalid: %v
• errMissingACLBindingRuleID
• token name too long
• client token missing policies or roles

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