hashicorp/nomad · error

failed to setup vault client: %v

Error message

failed to setup vault client: %v

What it means

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.

Source

Thrown at client/client.go:609

	// Set the preconfigured list of static servers
	if len(cfg.Servers) > 0 {
		if _, err := c.setServersImpl(cfg.Servers, true); err != nil {
			logger.Warn("none of the configured servers are valid", "error", err)
		}
	}

	// Setup Consul discovery if enabled
	if cfg.GetDefaultConsul().ClientAutoJoin != nil && *cfg.GetDefaultConsul().ClientAutoJoin {
		c.shutdownGroup.Go(c.consulDiscovery)
		if c.servers.NumServers() == 0 {
			// No configured servers; trigger discovery manually
			c.triggerDiscoveryCh <- struct{}{}
		}
	}

	// Setup the vault client for token and secret renewals
	if err := c.setupVaultClients(); err != nil {
		return nil, fmt.Errorf("failed to setup vault client: %v", err)
	}

	// wait until drivers are healthy before restoring or registering with servers
	select {
	case <-c.fpInitialized:
	case <-time.After(batchFirstFingerprintsProcessingGrace):
		logger.Warn("batch fingerprint operation timed out; proceeding to register with fingerprinted plugins so far")
	}

	// Attempt to pull the node identity from the state database. If the client
	// is starting for the first time, this will be empty, so avoid an
	// unnecessary set call to the client atomic. This needs to happen before we
	// start heartbeating to avoid unnecessary identity generation and load on
	// the Nomad servers.
	//
	// If the DB returns an error, it is more than likely that the full
	// restoration will fail. It isn't terminal for us at this point though, as
	// we can generate a new identity on registration.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped inner error to confirm which Vault client setup failed.
2. If Vault is no longer used, remove/fix the vault stanza in the client config (and server config) and restart.
3. Verify connectivity and TLS settings to the Vault cluster(s) configured in server { vault {} }.
4. Clear stale Vault cluster config from the client state if a retired cluster is being retried.

Example fix

// before
client { /* inherits stale vault cluster */ }
// after
server { vault { enabled = false } }
# restart client so setupVaultClients skips Vault bootstrap

// before starting the client, verify configured Vault clusters are reachable and TLS valid
for _, vc := range vaultClusters {
    resp, err := http.Get(vc.Addr + "/v1/sys/health")
    if err != nil {
        return fmt.Errorf("vault %s unreachable: %w", vc.Addr, err)
    }
    resp.Body.Close()
}

client, err := client.NewClient(cfg, logger)
if err != nil && strings.Contains(err.Error(), "failed to setup vault client") {
    logger.Error("vault client setup failed; check server vault config and connectivity", "cause", err)
    // remediate: fix vault stanza or disable vault, then restart the agent
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to initialize client: %v
• fingerprinting failed: %v
• failed to initialize process manager: %w
• Failed to initialize the Vault client config for %s: %v
• Failed to initialize Vault client for %s: %s

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/0069f5a3627f46f6. Report an issue: GitHub.