{"record":{"id":"013a3af288e9bf31","repo":"hashicorp/nomad","slug":"could-not-create-consul-binding-rule-w","errorCode":null,"errorMessage":"[✘] Could not create Consul binding rule: %w","messagePattern":"\\[✘\\] Could not create Consul binding rule: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/setup_consul.go","lineNumber":536,"sourceCode":"\treturn slices.ContainsFunc(\n\t\texistingRules,\n\t\tfunc(r *api.ACLBindingRule) bool {\n\t\t\treturn r.AuthMethod == rule.AuthMethod &&\n\t\t\t\tr.BindType == rule.BindType &&\n\t\t\t\tr.BindName == rule.BindName &&\n\t\t\t\tr.Selector == rule.Selector\n\t\t})\n}\n\nfunc (s *SetupConsulCommand) createBindingRules(rule *api.ACLBindingRule) error {\n\two := &api.WriteOptions{}\n\tif s.consulEnt {\n\t\t// binding rules are created in the default ns\n\t\two.Namespace = \"default\"\n\t}\n\t_, _, err := s.client.ACL().BindingRuleCreate(rule, wo)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"[✘] Could not create Consul binding rule: %w\", err)\n\t}\n\n\ts.Ui.Info(fmt.Sprintf(\"[✔] Created binding rule for auth method %q.\", rule.AuthMethod))\n\n\treturn nil\n}\n\nfunc (s *SetupConsulCommand) roleExists() bool {\n\texistingRoles, _, _ := s.client.ACL().RoleList(nil)\n\treturn slices.ContainsFunc(\n\t\texistingRoles,\n\t\tfunc(r *api.ACLRole) bool { return r.Name == consulRoleTasks })\n}\n\nfunc (s *SetupConsulCommand) createRoleForTasks() error {\n\t_, _, err := s.client.ACL().RoleCreate(&api.ACLRole{\n\t\tName:        consulRoleTasks,\n\t\tDescription: \"Role for Nomad tasks using workload identities\",","sourceCodeStart":518,"sourceCodeEnd":554,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/setup_consul.go#L518-L554","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["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.","Check the Consul token has acl:write: `consul acl token read -self`; export a sufficient CONSUL_HTTP_TOKEN.","Verify Consul connectivity (`consul members`, CONSUL_HTTP_ADDR) and read the wrapped underlying error for the exact API rejection.","Fix the root cause and re-run `nomad setup consul`; the command skips resources that already exist."],"exampleFix":"# before\nnomad setup consul   # auth method missing -> binding rule create fails\n// after\nconsul acl auth-method list                    # confirm nomad-workloads\nexport CONSUL_HTTP_TOKEN=<acl-write-token>\nnomad setup consul                             # re-run to create missing pieces","handlingStrategy":"try-catch","validationCode":"// pre-flight: auth method must exist and token must write ACLs\nmethods, _, err := s.client.ACL().AuthMethodList(nil)\nif err != nil { return err }\nvar found bool\nfor _, m := range methods { if m.Name == \"nomad-workloads\" { found = true } }\nif !found { return fmt.Errorf(\"auth method nomad-workloads missing; it must be created before binding rules\") }","typeGuard":null,"tryCatchPattern":"_, _, err := s.client.ACL().BindingRuleCreate(rule, wo)\nif err != nil {\n    if strings.Contains(err.Error(), \"Permission denied\") {\n        return fmt.Errorf(\"token lacks acl:write for binding rules: %w\", err)\n    }\n    return fmt.Errorf(\"[✘] Could not create Consul binding rule: %w\", err)\n}","preventionTips":["Run the full nomad setup flow in order so the auth method is created before binding rules.","Never manually delete the auth method without also expecting the setup to recreate it before rules.","Use a token with acl:write; verify with `consul acl token read -self`.","Re-run `nomad setup consul` after partial failures — it reconciles missing pieces.","On Enterprise, ensure namespace targeting (default) matches your Consul setup."],"tags":["consul","acl","setup"],"backgroundTag":"consul-api-error","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}