microsoft/aspire · error · ArgumentException

' ' is not a valid value.

Error message

'{roles[i]}' is not a valid {nameof(AzureOpenAIRole)} value.

What it means

WithRoleAssignments maps each AzureOpenAIRole enum value to the corresponding Azure.Provisioning CognitiveServicesBuiltInRole. If a role value has no mapping in the switch expression, the library throws this ArgumentException because it cannot translate the role into a built-in role assignment. This typically indicates a new AzureOpenAIRole member was added without updating this extension, or an invalid cast produced an out-of-range value.

Solutions

1. Use only the supported AzureOpenAIRole members: CognitiveServicesOpenAIContributor, CognitiveServicesOpenAIUser, CognitiveServicesUser
2. Parse role names with Enum.TryParse<AzureOpenAIRole> and validate each value against the supported set before calling WithRoleAssignments
3. Update Aspire.Hosting.Azure.CognitiveServices (and Azure.Provisioning) packages so new enum members have mappings

Example fix

// before
var role = (AzureOpenAIRole)intValue; // unmapped value -> ArgumentException
builder.AddOpenAI("ai").WithRoleAssignments(target, [role]);
// after
if (Enum.IsDefined(role) && role is AzureOpenAIRole.CognitiveServicesOpenAIContributor
    or AzureOpenAIRole.CognitiveServicesOpenAIUser or AzureOpenAIRole.CognitiveServicesUser)
{
    builder.AddOpenAI("ai").WithRoleAssignments(target, [role]);
}

AzureOpenAIRole[] supported = [AzureOpenAIRole.CognitiveServicesOpenAIContributor, AzureOpenAIRole.CognitiveServicesOpenAIUser, AzureOpenAIRole.CognitiveServicesUser];
if (roles.Any(r => !supported.Contains(r))) throw new InvalidOperationException($"Unsupported AzureOpenAIRole: {roles.First(r => !supported.Contains(r))}");

static bool IsValidAzureOpenAIRole(AzureOpenAIRole r) => r is AzureOpenAIRole.CognitiveServicesOpenAIContributor or AzureOpenAIRole.CognitiveServicesOpenAIUser or AzureOpenAIRole.CognitiveServicesUser;

try { builder.WithRoleAssignments(target, roles); } catch (ArgumentException ex) when (ex.ParamName == "roles") { /* log and surface unsupported role */ }

When it happens

Trigger: Calling WithRoleAssignments on an Azure OpenAI resource builder with an AzureOpenAIRole value not handled by the switch (CognitiveServicesOpenAIContributor, CognitiveServicesOpenAIUser, CognitiveServicesUser are the only supported values), e.g. after casting an arbitrary int/enum to AzureOpenAIRole or using a newer enum member with an older extension version.

Common situations: Dynamically constructing role lists from config files or strings cast to the enum; upgrading the Azure.Provisioning / Aspire packages where a new AzureOpenAIRole member exists but the extension mapping lags; typos leading to default enum values like 0 not corresponding to a defined member.

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

• Invalid Azure AI Search role
• Role ' ' at index is not a valid AzureAppConfigurationRole…
• ' ' is not a valid AzureContainerRegistryRole value.
• ' ' is not a valid AzureKeyVaultRole value.
• ' ' is not a valid value.

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.CognitiveServices/AzureOpenAIExtensions.cs:286

        this IResourceBuilder<T> builder,
        IResourceBuilder<AzureOpenAIResource> target,
        params AzureOpenAIRole[] roles)
        where T : IResource
    {
        if (roles is null || roles.Length == 0)
        {
            return builder.WithRoleAssignments(target, Array.Empty<CognitiveServicesBuiltInRole>());
        }

        var builtInRoles = new CognitiveServicesBuiltInRole[roles.Length];
        for (var i = 0; i < roles.Length; i++)
        {
            builtInRoles[i] = roles[i] switch
            {
                AzureOpenAIRole.CognitiveServicesOpenAIContributor => CognitiveServicesBuiltInRole.CognitiveServicesOpenAIContributor,
                AzureOpenAIRole.CognitiveServicesOpenAIUser => CognitiveServicesBuiltInRole.CognitiveServicesOpenAIUser,
                AzureOpenAIRole.CognitiveServicesUser => CognitiveServicesBuiltInRole.CognitiveServicesUser,
                _ => throw new ArgumentException($"'{roles[i]}' is not a valid {nameof(AzureOpenAIRole)} value.", nameof(roles))
            };
        }

        return builder.WithRoleAssignments(target, builtInRoles);
    }
}

View on GitHub (pinned to 25830f84bd)