What causes "Invalid Azure AI Search role: {roles[i]}." in microsoft/aspire?

microsoft/aspire · error · ArgumentException

Invalid Azure AI Search role

Error message

Invalid Azure AI Search role: {roles[i]}.

What it means

WithRoleAssignments for Azure AI Search maps each public AzureSearchRole enum value to the corresponding provisioning SearchBuiltInRole; any value outside SearchIndexDataContributor, SearchIndexDataReader, or SearchServiceContributor falls through the switch and throws ArgumentException. This guards against future or misused enum members that have no mapping to an Azure built-in role.

Solutions

Use only AzureSearchRole.SearchIndexDataContributor, SearchIndexDataReader, or SearchServiceContributor when calling WithRoleAssignments.
Update to the latest Aspire.Hosting.Azure.Search package, where newly added roles may be mapped.
Check each element of the roles array — the message names roles[i], so find the offending index and correct it.
If you need an unmapped Azure role, use the underlying provisioning API directly instead of the extension.

Example fix

// before
builder.WithRoleAssignments(search, (AzureSearchRole)42);
// after
builder.WithRoleAssignments(search, AzureSearchRole.SearchIndexDataContributor, AzureSearchRole.SearchIndexDataReader);

Defensive patterns

Strategy: validation

Validate before calling

static readonly AzureSearchRole[] AllowedSearchRoles =
[
    AzureSearchRole.SearchIndexDataContributor,
    AzureSearchRole.SearchIndexDataReader,
    AzureSearchRole.SearchServiceContributor
];

if (roles.Any(r => !AllowedSearchRoles.Contains(r)))
{
    throw new ArgumentException("Unsupported AzureSearchRole value.");
}
builder.WithRoleAssignments(search, roles);

Type guard

static bool IsValidSearchRole(AzureSearchRole r) =>
    r is AzureSearchRole.SearchIndexDataContributor
      or AzureSearchRole.SearchIndexDataReader
      or AzureSearchRole.SearchServiceContributor;

Prevention

Only pass the three supported AzureSearchRole members; never cast arbitrary integers into the enum.
Avoid default(AzureSearchRole) when building role arrays.
Update the package when new role members are released so mappings exist.
Keep role-assignment calls centralized so a bad role is caught in one place.

When it happens

Trigger: Calling builder.WithRoleAssignments(...) on an Azure AI Search resource with an AzureSearchRole value that is not one of the three supported members (or default(0) if such a value exists).

Common situations: Passing a cast or default-initialized AzureSearchRole; upgrading packages where new enum members exist without a mapping; copying code from other Azure resources (e.g. Service Bus roles) into the Search API.

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/76e3b55be929423a. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Search/AzureSearchExtensions.cs:173

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

        var builtInRoles = new SearchBuiltInRole[roles.Length];
        for (var i = 0; i < roles.Length; i++)
        {
            builtInRoles[i] = roles[i] switch
            {
                AzureSearchRole.SearchIndexDataContributor => SearchBuiltInRole.SearchIndexDataContributor,
                AzureSearchRole.SearchIndexDataReader => SearchBuiltInRole.SearchIndexDataReader,
                AzureSearchRole.SearchServiceContributor => SearchBuiltInRole.SearchServiceContributor,
                _ => throw new ArgumentException($"Invalid Azure AI Search role: {roles[i]}.", nameof(roles))
            };
        }

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

View on GitHub (pinned to 25830f84bd)