hashicorp/nomad · error

[✘] Could not create Consul binding rule: %w

Error message

[✘] Could not create Consul binding rule: %w

What it means

createBindingRules creates an ACL binding rule mapping claims from the nomad-workloads auth method to Consul identities, via ACL().BindingRuleCreate. Any API error (connectivity, permissions, invalid rule, auth method missing) is wrapped here. Notably the rule targets the nomad-workloads auth method, so a prior failure to create that method cascades into this error.

Source

Thrown at command/setup_consul.go:536

	return slices.ContainsFunc(
		existingRules,
		func(r *api.ACLBindingRule) bool {
			return r.AuthMethod == rule.AuthMethod &&
				r.BindType == rule.BindType &&
				r.BindName == rule.BindName &&
				r.Selector == rule.Selector
		})
}

func (s *SetupConsulCommand) createBindingRules(rule *api.ACLBindingRule) error {
	wo := &api.WriteOptions{}
	if s.consulEnt {
		// binding rules are created in the default ns
		wo.Namespace = "default"
	}
	_, _, err := s.client.ACL().BindingRuleCreate(rule, wo)
	if err != nil {
		return fmt.Errorf("[✘] Could not create Consul binding rule: %w", err)
	}

	s.Ui.Info(fmt.Sprintf("[✔] Created binding rule for auth method %q.", rule.AuthMethod))

	return nil
}

func (s *SetupConsulCommand) roleExists() bool {
	existingRoles, _, _ := s.client.ACL().RoleList(nil)
	return slices.ContainsFunc(
		existingRoles,
		func(r *api.ACLRole) bool { return r.Name == consulRoleTasks })
}

func (s *SetupConsulCommand) createRoleForTasks() error {
	_, _, err := s.client.ACL().RoleCreate(&api.ACLRole{
		Name:        consulRoleTasks,
		Description: "Role for Nomad tasks using workload identities",

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure the auth method exists first: `consul acl auth-method list` — re-run the setup or `consul acl auth-method create` for nomad-workloads if missing.
2. Check the Consul token has acl:write: `consul acl token read -self`; export a sufficient CONSUL_HTTP_TOKEN.
3. Verify Consul connectivity (`consul members`, CONSUL_HTTP_ADDR) and read the wrapped underlying error for the exact API rejection.
4. Fix the root cause and re-run `nomad setup consul`; the command skips resources that already exist.

Example fix

# before
nomad setup consul   # auth method missing -> binding rule create fails
// after
consul acl auth-method list                    # confirm nomad-workloads
export CONSUL_HTTP_TOKEN=<acl-write-token>
nomad setup consul                             # re-run to create missing pieces

// pre-flight: auth method must exist and token must write ACLs
methods, _, err := s.client.ACL().AuthMethodList(nil)
if err != nil { return err }
var found bool
for _, m := range methods { if m.Name == "nomad-workloads" { found = true } }
if !found { return fmt.Errorf("auth method nomad-workloads missing; it must be created before binding rules") }

_, _, err := s.client.ACL().BindingRuleCreate(rule, wo)
if err != nil {
    if strings.Contains(err.Error(), "Permission denied") {
        return fmt.Errorf("token lacks acl:write for binding rules: %w", err)
    }
    return fmt.Errorf("[✘] Could not create Consul binding rule: %w", err)
}

When it happens

Trigger: `nomad setup consul` calls BindingRuleCreate and it errors: Consul unreachable, token lacks acl:write, the referenced auth method 'nomad-workloads' doesn't exist because createAuthMethod failed earlier, or Enterprise namespace 'default' targeting is rejected.

Common situations: Skipped or failed auth-method creation in an earlier setup step; insufficient CONSUL_HTTP_TOKEN privileges; Consul agent addr wrong; re-running setup after partially deleting Consul resources so the rule's auth method is gone.

Related errors

• [✘] Could not create Consul auth method: %w
• [✘] Could not write namespace %q: %w
• [✘] Could not create Consul role: %w
• [✘] Could not create Consul policy: %w
• no one-time token returned

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