hashicorp/nomad · error

no Vault cluster named: %q

Error message

no Vault cluster named: %q

What it means

Client.VaultClient looks up a previously created Vault client by cluster name; if no cluster with that name was configured/initialized, it returns this error. Callers requesting a Vault client for a cluster that doesn't exist on this node get this lookup failure instead of a nil pointer.

Source

Thrown at client/client.go:3033

	for _, vaultConfig := range vaultConfigs {
		vaultClient, err := vaultclient.NewVaultClient(vaultConfig, c.logger)
		if err != nil {
			return err
		}
		if vaultClient == nil {
			c.logger.Error("failed to create vault client", "name", vaultConfig.Name)
			return fmt.Errorf("failed to create vault client for cluster %q", vaultConfig.Name)
		}
		c.vaultClients[vaultConfig.Name] = vaultClient
	}

	return nil
}

func (c *Client) VaultClient(cluster string) (vaultclient.VaultClient, error) {
	vaultClient, ok := c.vaultClients[cluster]
	if !ok {
		return nil, fmt.Errorf("no Vault cluster named: %q", cluster)
	}

	return vaultClient, nil
}

// setupNomadServiceRegistrationHandler sets up the registration handler to use
// for native service discovery.
func (c *Client) setupNomadServiceRegistrationHandler() {
	cfg := nsd.ServiceRegistrationHandlerCfg{
		Datacenter: c.Datacenter(),
		Enabled:    c.GetConfig().NomadServiceDiscovery,
		NodeID:     c.NodeID(),
		NodeSecret: c.secretNodeID(),
		Region:     c.Region(),
		RPCFn:      c.RPC,
		CheckWatcher: serviceregistration.NewCheckWatcher(
			c.logger, nsd.NewStatusGetter(c.checkStore),
		),

View on GitHub (pinned to 482b49bf1a)

Solutions

1. List the vault clusters configured on the client and use an exact (case-sensitive) name match in the job/task
2. Enable and correctly configure the vault stanza on the Nomad client for that cluster
3. Check client startup logs for earlier vault client setup failures (e.g. error 808) and fix the root cause
4. Fix the caller (job spec / plugin code) to request the default cluster when only one is configured

Example fix

// before
vault {}
# job requests
vault { cluster = "prod-vault" }
// after
vault {
  default_cluster_name = "prod-vault"
  address = "https://vault:8200"
}

// resolve the cluster name against configured clusters before requesting a client
clusters := client.ConfiguredVaultClusters() // or read from config
if !slices.Contains(clusters, requestedCluster) {
	return fmt.Errorf("vault cluster %q not configured; have %v", requestedCluster, clusters)
}

func hasVaultCluster(c *client.Client, name string) bool {
	_, err := c.VaultClient(name)
	return err == nil
}

vc, err := nomadClient.VaultClient(cluster)
if err != nil {
	logger.Error("vault cluster lookup failed", "cluster", cluster, "err", err)
	vc, err = nomadClient.VaultClient(defaultClusterName)
	if err != nil { return err }
}

When it happens

Trigger: Calling client.VaultClient("name") (or code paths that fetch the default cluster's client) where the name does not match any key in c.vaultClients — i.e. the cluster was never configured in the client's vault stanza or setup failed earlier.

Common situations: Job/task requests a Vault cluster name that differs from the configured one (case-sensitive mismatch); Vault disabled on the client; setup failed earlier leaving c.vaultClients empty; referring to the legacy single-cluster API with a custom name.

Related errors

• Vault cluster %q is disabled or not configured
• No client configuration found for Vault cluster %s
• failed to recover vault token from %s: %v
• failed to write Vault token to disk: %w
• failed to create vault client for cluster %q

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