failed to construct Azure Key Vault client to retrieve key v

Error message

failed to construct Azure Key Vault client to retrieve key version: %w

What it means

After obtaining a token credential, ensureKeyHasVersion builds an azkeys client to query the key. This error means azkeys.NewClient rejected the arguments — usually because key.VaultURL is malformed or empty.

Source

Thrown at azkv/keysource.go:189

}

func (key *MasterKey) ensureKeyHasVersion(ctx context.Context) error {
	if key.Version != "" {
		// Nothing to do
		return nil
	}

	token, err := key.getTokenCredential()

	if err != nil {
		log.WithFields(logrus.Fields{"key": key.Name, "version": key.Version}).Info("Encryption failed")
		return fmt.Errorf("failed to get Azure token credential to retrieve key version: %w", err)
	}

	c, err := azkeys.NewClient(key.VaultURL, token, key.clientOptions)
	if err != nil {
		log.WithFields(logrus.Fields{"key": key.Name, "version": key.Version}).Info("Encryption failed")
		return fmt.Errorf("failed to construct Azure Key Vault client to retrieve key version: %w", err)
	}

	kdetail, err := c.GetKey(ctx, key.Name, key.Version, nil)
	if err != nil {
		log.WithFields(logrus.Fields{"key": key.Name, "version": key.Version}).Info("Encryption failed")
		return fmt.Errorf("failed to fetch Azure Key to retrieve key version: %w", err)
	}
	key.Version = kdetail.Key.KID.Version()

	log.WithFields(logrus.Fields{"key": key.Name, "version": key.Version}).Info("Version fetch succeeded")
	return nil
}

// EncryptContext takes a SOPS data key, encrypts it with Azure Key Vault, and stores
// the result in the EncryptedKey field.
func (key *MasterKey) EncryptContext(ctx context.Context, dataKey []byte) error {
	token, err := key.getTokenCredential()
	if err != nil {

View on GitHub (pinned to 13442bb981)

Solutions

Check that the vault URL in the key identifier is a full https URL like https://myvault.vault.azure.net
Print/inspect the key's VaultURL value before client construction (log or debug)
Re-enter the key URL in .sops.yaml without typos or line breaks
Upgrade the Azure SDK modules if the error persists with a clearly valid URL

Example fix

// before
azure_kv: myvault.vault.azure.net/keys/k1
// after
azure_kv: https://myvault.vault.azure.net/keys/k1

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(key.VaultURL)
if err != nil || u.Scheme != "https" || u.Host == "" {
    return fmt.Errorf("invalid vault URL %q: must be an absolute https URL", key.VaultURL)
}

Type guard

func isValidVaultURL(vaultURL string) bool {
    u, err := url.Parse(vaultURL)
    return err == nil && u.Scheme == "https" && u.Host != ""
}

Try / catch

err := ensureVersion(key)
if strings.Contains(err.Error(), "failed to construct Azure Key Vault client") {
    return fmt.Errorf("check the vault URL in the key identifier: %w", err)
}

Prevention

Always use full https vault URLs in azure_kv entries
Avoid hand-editing key metadata in .sops.yaml
Validate URLs with a regex/url.Parse before storing

When it happens

Trigger: ensureKeyHasVersion calls azkeys.NewClient(key.VaultURL, token, key.clientOptions) and the SDK returns an error, typically an invalid vault URL (not an absolute https URL) passed via the key URL or sops config.

Common situations: Vault URL missing https:// scheme; empty vault URL after a bad parse; trailing characters or a host-only value without scheme; corporate proxy altering the endpoint configuration.

Related errors

AI-assisted analysis of getsops/sops@13442bb981 (2026-09-01). Data as JSON: /api/errors/f1854e36d137b3a7. Report an issue: GitHub.