{"record":{"id":"0069f5a3627f46f6","repo":"hashicorp/nomad","slug":"failed-to-setup-vault-client-v","errorCode":null,"errorMessage":"failed to setup vault client: %v","messagePattern":"failed to setup vault client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":609,"sourceCode":"\t// Set the preconfigured list of static servers\n\tif len(cfg.Servers) > 0 {\n\t\tif _, err := c.setServersImpl(cfg.Servers, true); err != nil {\n\t\t\tlogger.Warn(\"none of the configured servers are valid\", \"error\", err)\n\t\t}\n\t}\n\n\t// Setup Consul discovery if enabled\n\tif cfg.GetDefaultConsul().ClientAutoJoin != nil && *cfg.GetDefaultConsul().ClientAutoJoin {\n\t\tc.shutdownGroup.Go(c.consulDiscovery)\n\t\tif c.servers.NumServers() == 0 {\n\t\t\t// No configured servers; trigger discovery manually\n\t\t\tc.triggerDiscoveryCh <- struct{}{}\n\t\t}\n\t}\n\n\t// Setup the vault client for token and secret renewals\n\tif err := c.setupVaultClients(); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to setup vault client: %v\", err)\n\t}\n\n\t// wait until drivers are healthy before restoring or registering with servers\n\tselect {\n\tcase <-c.fpInitialized:\n\tcase <-time.After(batchFirstFingerprintsProcessingGrace):\n\t\tlogger.Warn(\"batch fingerprint operation timed out; proceeding to register with fingerprinted plugins so far\")\n\t}\n\n\t// Attempt to pull the node identity from the state database. If the client\n\t// is starting for the first time, this will be empty, so avoid an\n\t// unnecessary set call to the client atomic. This needs to happen before we\n\t// start heartbeating to avoid unnecessary identity generation and load on\n\t// the Nomad servers.\n\t//\n\t// If the DB returns an error, it is more than likely that the full\n\t// restoration will fail. It isn't terminal for us at this point though, as\n\t// we can generate a new identity on registration.","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L591-L627","documentation":"NewClient returns this when c.setupVaultClients() fails. This step creates the Vault token/secret renewal clients used for managing Vault tokens handed to tasks; a failure here (e.g. invalid Vault config) stops client startup.","triggerScenarios":"setupVaultClients errors because the server_config/Vault cluster was unreachable during bootstrap, the Vault API client could not be constructed from the client's config, or the client tried to create a renewal when Vault is disabled but stale config remains.","commonSituations":"client { vault {} } blocks referencing Vault clusters the client cannot reach; stale Vault config cached in state from a retired Vault cluster; TLS misconfiguration (bad CA, hostname) when constructing the Vault client.","solutions":["Read the wrapped inner error to confirm which Vault client setup failed.","If Vault is no longer used, remove/fix the vault stanza in the client config (and server config) and restart.","Verify connectivity and TLS settings to the Vault cluster(s) configured in server { vault {} }.","Clear stale Vault cluster config from the client state if a retired cluster is being retried."],"exampleFix":"// before\nclient { /* inherits stale vault cluster */ }\n// after\nserver { vault { enabled = false } }\n# restart client so setupVaultClients skips Vault bootstrap","handlingStrategy":"validation","validationCode":"// before starting the client, verify configured Vault clusters are reachable and TLS valid\nfor _, vc := range vaultClusters {\n    resp, err := http.Get(vc.Addr + \"/v1/sys/health\")\n    if err != nil {\n        return fmt.Errorf(\"vault %s unreachable: %w\", vc.Addr, err)\n    }\n    resp.Body.Close()\n}","typeGuard":null,"tryCatchPattern":"client, err := client.NewClient(cfg, logger)\nif err != nil && strings.Contains(err.Error(), \"failed to setup vault client\") {\n    logger.Error(\"vault client setup failed; check server vault config and connectivity\", \"cause\", err)\n    // remediate: fix vault stanza or disable vault, then restart the agent\n}","preventionTips":["Keep client and server vault stanzas in sync; disable Vault on both if unused","Validate Vault CA certs and addresses before rolling them out to clients","Cleanly retire Vault clusters so clients don't retain stale cluster config in state","Monitor Vault health from Nomad clients to catch reachability regressions early"],"tags":["client","vault","initialization"],"backgroundTag":"client-initialization-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"}