What causes "'{roles[i]}' is not a valid AzureKeyVaultRole value." in microsoft/aspire?

Use only defined AzureKeyVaultRole enum members (e.g. AzureKeyVaultRole.KeyVaultAdministrator, KeyVaultSecretsUser, etc.) in the roles collection.

microsoft/aspire · error · ArgumentException

' ' is not a valid AzureKeyVaultRole value.

Error message

'{roles[i]}' is not a valid AzureKeyVaultRole value.

What it means

WithRoleAssignments maps each AzureKeyVaultRole enum value to a KeyVaultBuiltInRole. The default arm of the switch expression throws ArgumentException when a role value in the supplied collection is not one of the known AzureKeyVaultRole members — typically from an invalid cast or an out-of-range enum value.

Solutions

Use only defined AzureKeyVaultRole enum members (e.g. AzureKeyVaultRole.KeyVaultAdministrator, KeyVaultSecretsUser, etc.) in the roles collection.
Validate/parse roles with Enum.TryParse before passing them.
Check that all packages producing the enum values are the same version to avoid mismatched enum definitions.

Example fix

// before
var roles = new[] { (AzureKeyVaultRole)int.Parse(config["role"]) };
vault.WithRoleAssignments(functionApp, roles);

// after
if (Enum.TryParse<AzureKeyVaultRole>(config["role"], out var role))
{
    vault.WithRoleAssignments(functionApp, new[] { role });
}

Defensive patterns

Strategy: validation

Validate before calling

if (roles.Any(r => !Enum.IsDefined(r)))
{
    throw new ArgumentException("Roles contain undefined AzureKeyVaultRole values.", nameof(roles));
}

Type guard

bool IsDefinedRole(AzureKeyVaultRole r) => Enum.IsDefined(r);

Try / catch

try { vault.WithRoleAssignments(target, roles); }
catch (ArgumentException ex) when (ex.Message.Contains("AzureKeyVaultRole")) { /* log and fix the role source */ }

Prevention

Parse roles with Enum.TryParse instead of casting ints.
Keep enum-producing packages on the same version across the solution.
Validate configuration-derived roles at startup.

When it happens

Trigger: Calling WithRoleAssignments on an Azure Key Vault resource builder passing a roles collection that contains an undefined or out-of-range AzureKeyVaultRole value, e.g. (AzureKeyVaultRole)999.

Common situations: Enum values obtained from configuration parsing, deserialization of stale saved models, or older/newer package versions where the enum gained or lost members.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

        var builtInRoles = new KeyVaultBuiltInRole[roles.Length];
        for (var i = 0; i < roles.Length; i++)
        {
            builtInRoles[i] = roles[i] switch
            {
                AzureKeyVaultRole.KeyVaultAdministrator => KeyVaultBuiltInRole.KeyVaultAdministrator,
                AzureKeyVaultRole.KeyVaultCertificateUser => KeyVaultBuiltInRole.KeyVaultCertificateUser,
                AzureKeyVaultRole.KeyVaultCertificatesOfficer => KeyVaultBuiltInRole.KeyVaultCertificatesOfficer,
                AzureKeyVaultRole.KeyVaultContributor => KeyVaultBuiltInRole.KeyVaultContributor,
                AzureKeyVaultRole.KeyVaultCryptoOfficer => KeyVaultBuiltInRole.KeyVaultCryptoOfficer,
                AzureKeyVaultRole.KeyVaultCryptoServiceEncryptionUser => KeyVaultBuiltInRole.KeyVaultCryptoServiceEncryptionUser,
                AzureKeyVaultRole.KeyVaultCryptoServiceReleaseUser => KeyVaultBuiltInRole.KeyVaultCryptoServiceReleaseUser,
                AzureKeyVaultRole.KeyVaultCryptoUser => KeyVaultBuiltInRole.KeyVaultCryptoUser,
                AzureKeyVaultRole.KeyVaultDataAccessAdministrator => KeyVaultBuiltInRole.KeyVaultDataAccessAdministrator,
                AzureKeyVaultRole.KeyVaultReader => KeyVaultBuiltInRole.KeyVaultReader,
                AzureKeyVaultRole.KeyVaultSecretsOfficer => KeyVaultBuiltInRole.KeyVaultSecretsOfficer,
                AzureKeyVaultRole.KeyVaultSecretsUser => KeyVaultBuiltInRole.KeyVaultSecretsUser,
                AzureKeyVaultRole.ManagedHsmContributor => KeyVaultBuiltInRole.ManagedHsmContributor,
                _ => throw new ArgumentException($"'{roles[i]}' is not a valid {nameof(AzureKeyVaultRole)} value.", nameof(roles))
            };
        }

        return builder.WithRoleAssignments(target, builtInRoles);
    }

    /// <summary>
    /// Gets a secret reference for the specified secret name from the Azure Key Vault resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="secretName">The name of the secret.</param>
    /// <returns>A reference to the secret.</returns>
    [AspireExport]
    public static IAzureKeyVaultSecretReference GetSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string secretName)
    {
        ArgumentNullException.ThrowIfNull(builder);

        return builder.Resource.GetSecret(secretName);

View on GitHub (pinned to 25830f84bd)