{"record":{"id":"493dd562e4bc5f3d","repo":"hashicorp/nomad","slug":"failed-to-initialize-vault-client-for-s-s","errorCode":null,"errorMessage":"Failed to initialize Vault client for %s: %s","messagePattern":"Failed to initialize Vault client for (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/fingerprint/vault.go","lineNumber":117,"sourceCode":"// fingerprintImpl fingerprints for a single Vault cluster\nfunc (f *VaultFingerprint) fingerprintImpl(cfg *config.VaultConfig, resp *FingerprintResponse) error {\n\tlogger := f.logger.With(\"cluster\", cfg.Name)\n\n\tstate, ok := f.states[cfg.Name]\n\tif !ok {\n\t\tstate = &vaultFingerprintState{}\n\t\tf.states[cfg.Name] = state\n\t}\n\n\t// Only create the client once to avoid creating too many connections to Vault\n\tif state.client == nil {\n\t\tvaultConfig, err := cfg.ApiConfig()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to initialize the Vault client config for %s: %v\", cfg.Name, err)\n\t\t}\n\t\tstate.client, err = vapi.NewClient(vaultConfig)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to initialize Vault client for %s: %s\", cfg.Name, err)\n\t\t}\n\t\tuseragent.SetHeaders(state.client)\n\t}\n\n\t// Connect to vault and parse its information\n\tstatus, err := state.client.Sys().SealStatus()\n\tif err != nil {\n\t\t// Print a message indicating that Vault is not available anymore\n\t\tif state.isAvailable {\n\t\t\tlogger.Info(\"Vault is unavailable\")\n\t\t}\n\t\tstate.isAvailable = false\n\t\treturn nil\n\t}\n\n\tif cfg.Name == structs.VaultDefaultCluster {\n\t\tresp.AddAttribute(\"vault.accessible\", strconv.FormatBool(true))\n\t\tresp.AddAttribute(\"vault.version\", strings.TrimPrefix(status.Version, \"Vault \"))","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/fingerprint/vault.go#L99-L135","documentation":"After the config is built, the Vault fingerprint calls vapi.NewClient(vaultConfig) to instantiate the API client. NewClient fails only if the config has no valid address (or an invalid URL), so this error means the Vault client could not be constructed despite the config passing ApiConfig().","triggerScenarios":"vapi.NewClient(vaultConfig) returns an error — the resulting config's address is empty or not a parseable URL when the fingerprint creates the Vault client.","commonSituations":"Vault address ends up empty because neither the job's vault block nor client/server config supplied one; templated address variable resolves to empty string; version drift where the client config previously defaulted the address.","solutions":["Ensure a vault address is set — in the job's vault block or via client config — so NewClient receives a valid URL","Check that the client's vault configuration (vault { address = ... } / VAULT_ADDR) is populated","Read the wrapped %s error which reports the exact URL parse problem","Pin/align Nomad versions across the cluster to avoid config-default changes"],"exampleFix":"// before (client config)\nclient {\n  enabled = true\n}\n// after\nclient {\n  enabled = true\n}\nvault {\n  address = \"https://vault.internal:8200\"\n}","handlingStrategy":"validation","validationCode":"addr := os.Getenv(\"VAULT_ADDR\")\nif addr == \"\" {\n    log.Fatal(\"VAULT_ADDR (or client vault.address) must be set before starting tasks with vault policies\")\n}\nif _, err := url.Parse(addr); err != nil {\n    log.Fatalf(\"VAULT_ADDR %q is not a valid URL: %v\", addr, err)\n}","typeGuard":"func hasVaultAddress(cfg *api.VaultConfig) bool {\n    return cfg != nil && cfg.Address != \"\"\n}","tryCatchPattern":"err := task.Run()\nif err != nil && strings.Contains(err.Error(), \"Failed to initialize Vault client\") {\n    log.Printf(\"vault client could not be constructed, check address config: %v\", err)\n    return RetryWithBackoff(recheckConfig) // only retry after config fixed\n}","preventionTips":["Set vault.address explicitly in client config rather than relying on defaults","Check that templated/interpolated address variables actually resolve to non-empty values","Keep Nomad agent and CLI versions aligned across the cluster","Verify VAULT_ADDR is exported in the client's service environment"],"tags":["vault","client","configuration"],"backgroundTag":"invalid-vault-config","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"}