microsoft/aspire · error · ArgumentException

' ' is not a valid value.

Error message

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

What it means

WithRoleAssignments for Azure SignalR throws ArgumentException when an element of the roles array does not map to a known AzureSignalRRole. The extension only accepts the defined enum values (SignalRContributor, SignalRAppServer, SignalRRestApiOwner) and validates each switch arm.

Solutions

  1. Use only defined AzureSignalRRole values: SignalRContributor, SignalRAppServer, SignalRRestApiOwner.
  2. Parse role names with Enum.TryParse and reject undefined values before calling WithRoleAssignments.
  3. Check the roles[i] value named in the exception message and remove or correct it.

Example fix

// before
var role = (AzureSignalRRole)int.Parse(config["Role"]); // may be undefined
signalr.WithRoleAssignments(app, role);

// after
if (!Enum.TryParse<AzureSignalRRole>(config["Role"], out var role) || !Enum.IsDefined(role))
{
    throw new InvalidOperationException($"Unknown SignalR role: {config["Role"]}");
}
signalr.WithRoleAssignments(app, role);
Defensive patterns

Strategy: validation

Validate before calling

foreach (var role in roles) { if (!Enum.IsDefined(typeof(AzureSignalRRole), role)) throw new InvalidOperationException($"Role {role} is not a defined AzureSignalRRole."); }

Type guard

static bool IsValidSignalRRole(AzureSignalRRole role) => Enum.IsDefined(typeof(AzureSignalRRole), role);

Try / catch

try { builder.WithRoleAssignments(target, roles); }
catch (ArgumentException ex) { /* log ex.Message; fix role values */ }

Prevention

When it happens

Trigger: Calling WithRoleAssignments with a roles array containing an out-of-range cast (e.g. (AzureSignalRRole)99) or an undefined enum member, typically at index i reported in the message.

Common situations: Casting raw ints from configuration into the enum; reading role names from config and parsing to enum without validation; library version differences where a role value no longer exists.

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.SignalR/AzureSignalRExtensions.cs:241

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

        var builtInRoles = new SignalRBuiltInRole[roles.Length];
        for (var i = 0; i < roles.Length; i++)
        {
            builtInRoles[i] = roles[i] switch
            {
                AzureSignalRRole.SignalRContributor => SignalRBuiltInRole.SignalRContributor,
                AzureSignalRRole.SignalRAppServer => SignalRBuiltInRole.SignalRAppServer,
                AzureSignalRRole.SignalRRestApiOwner => SignalRBuiltInRole.SignalRRestApiOwner,
                _ => throw new ArgumentException($"'{roles[i]}' is not a valid {nameof(AzureSignalRRole)} value.", nameof(roles))
            };
        }

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

View on GitHub (pinned to 25830f84bd)