{"record":{"id":"e9dad14ab096d375","repo":"hashicorp/nomad","slug":"could-not-create-consul-auth-method-w","errorCode":null,"errorMessage":"[✘] Could not create Consul auth method: %w","messagePattern":"\\[✘\\] Could not create Consul auth method: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/setup_consul.go","lineNumber":478,"sourceCode":"\treturn method, nil\n}\n\nfunc (s *SetupConsulCommand) createAuthMethod(authMethod *api.ACLAuthMethod) error {\n\two := &api.WriteOptions{}\n\tif s.consulEnt {\n\t\t// auth methods are created in the default ns\n\t\two.Namespace = \"default\"\n\t}\n\n\t_, _, err := s.client.ACL().AuthMethodCreate(authMethod, wo)\n\tif err != nil {\n\t\tif strings.Contains(err.Error(), \"error checking JWKSURL\") {\n\t\t\ts.Ui.Error(fmt.Sprintf(\n\t\t\t\t\"error: Nomad JWKS endpoint unreachable, verify that Nomad is running and that the JWKS URL %s is reachable by Consul\", s.jwksURL,\n\t\t\t))\n\t\t\tos.Exit(1)\n\t\t}\n\t\treturn fmt.Errorf(\"[✘] Could not create Consul auth method: %w\", err)\n\t}\n\n\ts.Ui.Info(fmt.Sprintf(\"[✔] Created auth method %q.\", authMethod.Name))\n\treturn nil\n}\n\nfunc (s *SetupConsulCommand) namespaceExists(ns string) bool {\n\tnsClient := s.client.Namespaces()\n\n\texistingNamespaces, _, _ := nsClient.List(nil)\n\treturn slices.ContainsFunc(\n\t\texistingNamespaces,\n\t\tfunc(n *api.Namespace) bool { return n.Name == ns })\n}\n\nfunc (s *SetupConsulCommand) createNamespace(ns string) error {\n\tnsClient := s.client.Namespaces()\n\tnamespace := &api.Namespace{","sourceCodeStart":460,"sourceCodeEnd":496,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/setup_consul.go#L460-L496","documentation":"createAuthMethod calls Consul's ACL API to create the 'nomad-workloads' JWT auth method. Any API error other than the special-cased unreachable-JWKS case is wrapped here. This is the generic failure point for Consul connectivity, ACL permission, or JWKS configuration problems reported by Consul.","triggerScenarios":"s.client.ACL().AuthMethodCreate(...) returns an error while running `nomad setup consul` — e.g. Consul agent unreachable, the Consul token lacks ACL write permission (acl:write on auth methods), or Consul rejects the auth method config (bad JWKSURL, missing allowed domains, entropy/acl not enabled).","commonSituations":"CONSUL_HTTP_TOKEN missing or token insufficient (needs acl:write); Consul agent not running or wrong -http-addr; ACL system not enabled in Consul; JWKS URL pointing at an unreachable Nomad address (other than the exact 'error checking JWKSURL' special case, e.g. TLS verification failure against JWKS).","solutions":["Check connectivity to Consul: `consul members` and `consul info`; fix -http-addr / CONSUL_HTTP_ADDR if the agent is not reachable.","Ensure the token has sufficient privileges: `consul acl token read -self` — it needs acl:write; use the initial management token or bootstrap ACLs (`consul acl bootstrap`).","Confirm the auth method config: verify -jwks-url is reachable from Consul (`curl <jwks-url>/.well-known/jwks.json` from the Consul agent host) and check Consul agent logs for the underlying API error.","Retry nomad setup after fixing; if the auth method already exists from a prior run, the setup command's idempotency check or manual deletion (`consul acl auth-method delete nomad-workloads`) may be needed."],"exampleFix":"# before\nnomad setup consul   # no token -> permission denied\n// after\nexport CONSUL_HTTP_TOKEN=<management-or-acl-write-token>\nnomad setup consul -jwks-url=https://nomad.example.com:4646/.well-known/jwks.json","handlingStrategy":"try-catch","validationCode":"// pre-flight checks before nomad setup\n// 1) Consul reachable:\n//    curl $CONSUL_HTTP_ADDR/v1/status/leader\n// 2) token can write ACLs:\n//    curl -H \"X-Consul-Token: $CONSUL_HTTP_TOKEN\" $CONSUL_HTTP_ADDR/v1/acl/token/self\n// 3) JWKS endpoint reachable from the Consul agent host:\n//    curl $JWKS_URL/.well-known/jwks.json","typeGuard":null,"tryCatchPattern":"_, _, err := s.client.ACL().AuthMethodCreate(method, wo)\nif err != nil {\n    if strings.Contains(err.Error(), \"error checking JWKSURL\") {\n        return fmt.Errorf(\"Nomad JWKS endpoint %s unreachable from Consul: %w\", s.jwksURL, err)\n    }\n    if strings.Contains(err.Error(), \"Permission denied\") {\n        return fmt.Errorf(\"Consul token lacks acl:write; set CONSUL_HTTP_TOKEN to a privileged token: %w\", err)\n    }\n    return fmt.Errorf(\"[✘] Could not create Consul auth method: %w\", err)\n}","preventionTips":["Export CONSUL_HTTP_TOKEN with acl:write (or use the management token) before running setup.","Verify Consul connectivity (consul members / curl /v1/status/leader) first.","Confirm the JWKS URL is reachable from the Consul agent's network, with correct TLS trust.","Check Consul agent logs for the underlying API rejection when the setup fails.","Ensure Nomad is running before nomad setup consul, since Consul validates the JWKS endpoint."],"tags":["consul","acl","network","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"}