hashicorp/nomad · error

failed to create vault client for cluster

Error message

failed to create vault client for cluster %q

What it means

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.

Solutions

1. Check the preceding Error log line which names the offending vaultConfig.Name
2. Review the vault stanza for that cluster: verify it is complete and uses a schema supported by your Nomad version
3. Remove unused/empty vault cluster blocks and restart the client
4. Upgrade to a Nomad version that supports your Vault configuration layout (single vs multi-cluster) and re-test

Example fix

// before
vault {
  enabled = true
  # no address/token configured
}
// after
vault {
  enabled = true
  address = "https://vault.service.consul:8200"
  token   = "<token-or-affected-approle>"
}

// validate each vault cluster config before client setup
for _, vc := range vaultConfigs {
	if vc.Name == "" || vc.Address == "" {
		return fmt.Errorf("vault cluster %q misconfigured: name and address required", vc.Name)
	}
}

vaultClient, err := vaultclient.NewVaultClient(cfg, logger)
if err != nil || vaultClient == nil {
	return fmt.Errorf("vault cluster %q: client unusable (err=%v)", cfg.Name, err)
}

When it happens

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

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

Related errors

• No client configuration found for Vault cluster
• Vault cluster is disabled or not configured
• Failed to initialize the Vault client config for
• Failed to initialize Vault client for
• failed to recover vault token from

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

Appendix: source

Thrown at client/client.go:3022

		Wranglers:           c.wranglers,
		Partitions:          c.partitions,
		Users:               c.users,
	}
}

// setupVaultClients created vault clients for each configured cluster
func (c *Client) setupVaultClients() error {

	c.vaultClients = map[string]vaultclient.VaultClient{}
	vaultConfigs := c.GetConfig().GetVaultConfigs(c.logger)
	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.

View on GitHub (pinned to 482b49bf1a)