{"record":{"id":"42abf595e81b5e68","repo":"hashicorp/nomad","slug":"could-not-create-consul-role-w","errorCode":null,"errorMessage":"[✘] Could not create Consul role: %w","messagePattern":"\\[✘\\] Could not create Consul role: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/setup_consul.go","lineNumber":558,"sourceCode":"\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\",\n\t\tPolicies:    []*api.ACLLink{{Name: consulPolicyName}},\n\t}, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"[✘] Could not create Consul role: %w\", err)\n\t}\n\n\ts.Ui.Info(fmt.Sprintf(\"[✔] Created role %q.\", consulRoleTasks))\n\treturn nil\n}\n\nfunc (s *SetupConsulCommand) policyExists() bool {\n\texistingPolicies, _, _ := s.client.ACL().PolicyList(nil)\n\treturn slices.ContainsFunc(\n\t\texistingPolicies,\n\t\tfunc(p *api.ACLPolicyListEntry) bool { return p.Name == consulPolicyName })\n}\n\nfunc (s *SetupConsulCommand) createPolicy() error {\n\t_, _, err := s.client.ACL().PolicyCreate(&api.ACLPolicy{\n\t\tName:  consulPolicyName,\n\t\tRules: string(consulPolicyBody),\n\t}, nil)","sourceCodeStart":540,"sourceCodeEnd":576,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/setup_consul.go#L540-L576","documentation":"createRoleForTasks creates the 'nomad-workloads' Consul role (linking the nomad-workloads policy) via ACL().RoleCreate. Any API error — connectivity, insufficient token privileges, invalid policy link, or role name conflict — is wrapped here.","triggerScenarios":"`nomad setup consul` calls RoleCreate and errors: Consul agent unreachable, the Consul token lacks acl:write (roles require management-level or appropriate privileges), or the referenced policy 'nomad-workloads' doesn't exist because createPolicy failed earlier in the sequence.","commonSituations":"CONSUL_HTTP_TOKEN missing or under-privileged (role creation typically needs acl:write); prior step failed so the policy link is invalid; wrong CONSUL_HTTP_ADDR; a role named nomad-workloads already exists in a conflicting state after a partially-failed setup.","solutions":["Check token privileges: `consul acl token read -self`; export CONSUL_HTTP_TOKEN with acl:write (management token is simplest).","Verify the policy exists: `consul acl policy list | grep nomad-workloads`; re-run setup or create the policy first if it's missing.","Confirm connectivity to the Consul agent (`consul members`, CONSUL_HTTP_ADDR) and inspect the wrapped error for the exact API message.","If the role exists in a broken state, `consul acl role delete -name nomad-workloads` (or update it) then re-run nomad setup."],"exampleFix":"# before\nnomad setup consul   # read-only token -> RoleCreate denied\n// after\nexport CONSUL_HTTP_TOKEN=<management-token>\nnomad setup consul","handlingStrategy":"try-catch","validationCode":"// pre-flight: policy must exist and token must write ACLs\npols, _, err := s.client.ACL().PolicyList(nil)\nif err != nil { return err }\nvar hasPolicy bool\nfor _, p := range pols { if p.Name == \"nomad-workloads\" { hasPolicy = true } }\nif !hasPolicy { return fmt.Errorf(\"policy nomad-workloads missing; create it before the role\") }\n_, _, err = s.client.ACL().RoleList(nil)\nif err != nil { return fmt.Errorf(\"token cannot manage roles: %v\", err) }","typeGuard":null,"tryCatchPattern":"_, _, err := s.client.ACL().RoleCreate(role, nil)\nif err != nil {\n    if strings.Contains(err.Error(), \"Permission denied\") {\n        return fmt.Errorf(\"token lacks acl:write; set CONSUL_HTTP_TOKEN to a privileged token: %w\", err)\n    }\n    return fmt.Errorf(\"[✘] Could not create Consul role: %w\", err)\n}","preventionTips":["Export CONSUL_HTTP_TOKEN with acl:write (management token) before nomad setup consul.","Ensure the nomad-workloads policy is created first — setup does this in order; don't skip steps.","Verify connectivity (consul members, CONSUL_HTTP_ADDR) before running setup.","If a stale nomad-workloads role exists, inspect with `consul acl role list` and reconcile before re-running.","Read the wrapped underlying error — it names Consul's exact rejection reason."],"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"}