microsoft/aspire · error · ArgumentException

Secret name can only contain ASCII letters (a-z, A-Z)…

Error message

Secret name can only contain ASCII letters (a-z, A-Z), digits (0-9), and dashes (-).

What it means

Azure Key Vault secret names may contain only ASCII letters (a-z, A-Z), digits (0-9), and dashes (-), enforced by the regex ^[a-zA-Z0-9-]+$. ValidateSecretName throws ArgumentException when the name contains any other character (underscores, dots, spaces, non-ASCII, or is empty).

Solutions

Replace invalid characters with dashes: secretName.Replace('_', '-').
Sanitize the name before calling AddSecret, e.g. Regex.Replace(name, "[^a-zA-Z0-9-]", "-").
Keep the secret name as an explicit short literal instead of deriving it from other identifiers.

Example fix

// before
kv.AddSecret("my_secret.name", ...);

// after
var safeName = Regex.Replace("my_secret.name", "[^a-zA-Z0-9-]", "-"); // "my-secret-name"
kv.AddSecret(safeName, ...);

Defensive patterns

Strategy: validation

Validate before calling

var sanitized = Regex.Replace(secretName ?? "", "[^a-zA-Z0-9-]", "-");
if (sanitized.Length == 0) throw new ArgumentException("Secret name cannot be empty after sanitization.");

Type guard

bool IsValidSecretName(string n) => !string.IsNullOrEmpty(n) && Regex.IsMatch(n, "^[a-zA-Z0-9-]+$");

Try / catch

try { kv.AddSecret(secretName, ...); }
catch (ArgumentException ex) when (ex.Message.Contains("ASCII letters")) { /* sanitize and retry */ }

Prevention

Sanitize identifiers (underscores, dots, spaces) to dashes before adding secrets.
Remember the regex allows only letters, digits, and dashes — no underscores.
Test generated names with the same regex used by the library.

When it happens

Trigger: Calling AddSecret with a secret name containing invalid characters such as '_', '.', ':', '/', spaces, or non-ASCII letters — or an empty string (which fails the + quantifier).

Common situations: Deriving secret names from connection or setting names that use underscores (e.g. 'My_Connection'), from user input, or from resource names that include dots; classic Azure naming differences trip developers up.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/308596fdbecc1f9f. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.KeyVault/AzureKeyVaultResourceExtensions.cs:396

        ValidateSecretName(secretName);

        var secret = new AzureKeyVaultSecretResource(name, secretName, builder.Resource, value);
        builder.Resource.Secrets.Add(secret);

        return builder.ApplicationBuilder.AddResource(secret).WithIconName("LockClosed").ExcludeFromManifest();
    }

    private static void ValidateSecretName(string secretName)
    {
        // Azure Key Vault secret names must be 1-127 characters long and contain only ASCII letters (a-z, A-Z), digits (0-9), and dashes (-)
        if (secretName.Length > 127)
        {
            throw new ArgumentException("Secret name cannot be longer than 127 characters.", nameof(secretName));
        }

        if (!AzureKeyVaultSecretNameRegex().IsMatch(secretName))
        {
            throw new ArgumentException("Secret name can only contain ASCII letters (a-z, A-Z), digits (0-9), and dashes (-).", nameof(secretName));
        }
    }

    [GeneratedRegex("^[a-zA-Z0-9-]+$")]
    private static partial Regex AzureKeyVaultSecretNameRegex();
}

View on GitHub (pinned to 25830f84bd)