{"record":{"id":"8ee41317b25afdf1","repo":"hashicorp/nomad","slug":"failed-to-create-vault-client-for-cluster-q","errorCode":null,"errorMessage":"failed to create vault client for cluster %q","messagePattern":"failed to create vault client for cluster %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":3022,"sourceCode":"\t\tWranglers:           c.wranglers,\n\t\tPartitions:          c.partitions,\n\t\tUsers:               c.users,\n\t}\n}\n\n// setupVaultClients created vault clients for each configured cluster\nfunc (c *Client) setupVaultClients() error {\n\n\tc.vaultClients = map[string]vaultclient.VaultClient{}\n\tvaultConfigs := c.GetConfig().GetVaultConfigs(c.logger)\n\tfor _, vaultConfig := range vaultConfigs {\n\t\tvaultClient, err := vaultclient.NewVaultClient(vaultConfig, c.logger)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif vaultClient == nil {\n\t\t\tc.logger.Error(\"failed to create vault client\", \"name\", vaultConfig.Name)\n\t\t\treturn fmt.Errorf(\"failed to create vault client for cluster %q\", vaultConfig.Name)\n\t\t}\n\t\tc.vaultClients[vaultConfig.Name] = vaultClient\n\t}\n\n\treturn nil\n}\n\nfunc (c *Client) VaultClient(cluster string) (vaultclient.VaultClient, error) {\n\tvaultClient, ok := c.vaultClients[cluster]\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"no Vault cluster named: %q\", cluster)\n\t}\n\n\treturn vaultClient, nil\n}\n\n// setupNomadServiceRegistrationHandler sets up the registration handler to use\n// for native service discovery.","sourceCodeStart":3004,"sourceCodeEnd":3040,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L3004-L3040","documentation":"When the client sets up Vault integration, it creates a VaultClient for each configured cluster. If NewVaultClient succeeds but returns a nil client (an unexpected/unsupported configuration the client treats as invalid), the client logs and returns this error naming the cluster. Note that an actual construction error is returned unwrapped; this specific error is for the nil-client case.","triggerScenarios":"vaultclient.NewVaultClient returns (nil, nil) for one of the configured vault clusters during client setup — i.e. the Vault cluster config produced no usable client object (invalid/empty cluster configuration), while no explicit error was raised.","commonSituations":"vault block enabled with a misconfigured or empty cluster entry; unsupported Vault config combination; leftover/vestigial cluster stanza after Nomad changed Vault config schema (multi-cluster support); typo'd cluster name in server config propagated to clients.","solutions":["Check the preceding Error log line which names the offending vaultConfig.Name","Review the vault stanza for that cluster: verify it is complete and uses a schema supported by your Nomad version","Remove unused/empty vault cluster blocks and restart the client","Upgrade to a Nomad version that supports your Vault configuration layout (single vs multi-cluster) and re-test"],"exampleFix":"// before\nvault {\n  enabled = true\n  # no address/token configured\n}\n// after\nvault {\n  enabled = true\n  address = \"https://vault.service.consul:8200\"\n  token   = \"<token-or-affected-approle>\"\n}","handlingStrategy":"validation","validationCode":"// validate each vault cluster config before client setup\nfor _, vc := range vaultConfigs {\n\tif vc.Name == \"\" || vc.Address == \"\" {\n\t\treturn fmt.Errorf(\"vault cluster %q misconfigured: name and address required\", vc.Name)\n\t}\n}","typeGuard":null,"tryCatchPattern":"vaultClient, err := vaultclient.NewVaultClient(cfg, logger)\nif err != nil || vaultClient == nil {\n\treturn fmt.Errorf(\"vault cluster %q: client unusable (err=%v)\", cfg.Name, err)\n}","preventionTips":["Keep the vault stanza schema matched to your Nomad version","Remove empty/unused vault cluster blocks from client config","Log and review the cluster name in vault errors","Test vault client setup in staging after Nomad upgrades"],"tags":["nomad-client","vault","configuration"],"backgroundTag":"vault-client-init-failed","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"}