microsoft/aspire · error · ArgumentException

Secret name cannot be longer than 127 characters.

Error message

Secret name cannot be longer than 127 characters.

What it means

Azure Key Vault limits secret names to 127 characters. ValidateSecretName enforces this before any resource is added, throwing ArgumentException with the parameter name 'secretName' when the name exceeds the limit.

Solutions

  1. Shorten the secret name to 127 characters or fewer.
  2. Trim or abbreviate the prefix/convention that produces the name (e.g. use short env codes like 'dev' instead of 'development').
  3. Add a name-validation step in your AppHost that asserts names fit the Azure limit before calling AddSecret.

Example fix

// before
kv.AddSecret($"{environment}-{application}-{resource}-connection-string");

// after
var secretName = $"{envCode}-{appCode}-{resCode}-cs"; // kept under 127 chars
kv.AddSecret(secretName, ...);
Defensive patterns

Strategy: validation

Validate before calling

if (secretName.Length > 127)
{
    throw new ArgumentException($"Secret name '{secretName}' exceeds the 127-character Azure Key Vault limit.");
}

Try / catch

try { kv.AddSecret(secretName, ...); }
catch (ArgumentException ex) when (ex.ParamName == "secretName") { /* shorten the name and retry */ }

Prevention

When it happens

Trigger: Calling AddSecret (or the secret-adding extensions that route through ValidateSecretName) with a secretName string longer than 127 characters.

Common situations: Auto-generated secret names built from long prefixes plus resource/parameter names, environment-specific prefixes concatenated together, or machine-generated identifiers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, [ResourceName] string name, string secretName, ReferenceExpression value)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(value);

        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)