hashicorp/nomad · error

failed to create vault client for cluster %q

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.

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)

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

• 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 validate volume %s, err: %w

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