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

Only pass named AzureStorageRole members (e.g. AzureStorageRole.StorageBlobDataContributor), not cast integers

microsoft/aspire · error · ArgumentException

' ' is not a valid value.

Error message

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

What it means

WithRoleAssignments maps each AzureStorageRole enum value to a StorageBuiltInRole via a switch expression with no default case for unmapped values; hitting the throw arm means a value outside the recognized set was passed. This guards the API against invalid or future enum members.

Solutions

Only pass named AzureStorageRole members (e.g. AzureStorageRole.StorageBlobDataContributor), not cast integers
Compare your enum usage against the members defined in the referenced Aspire.Hosting.Azure.Storage version
Parse untrusted input with Enum.TryParse<AzureStorageRole> before calling WithRoleAssignments

Example fix

// before
storage.WithRoleAssignments(identity, (AzureStorageRole)42);
// after
storage.WithRoleAssignments(identity, AzureStorageRole.StorageBlobDataContributor);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(AzureStorageRole), role))
    throw new ArgumentException($"'{role}' is not a defined AzureStorageRole value.");

Type guard

static bool IsValidStorageRole(AzureStorageRole role) => Enum.IsDefined(role);

Try / catch

try { storage.WithRoleAssignments(identity, roles); }
catch (ArgumentException ex) when (ex.Message.Contains("not a valid AzureStorageRole")) { /* log and surface invalid role */ }

Prevention

Use named enum members only; never cast integers or strings into AzureStorageRole
Parse untrusted role input with Enum.TryParse before calling WithRoleAssignments
Match enum member usage to the exact package version referenced

When it happens

Trigger: Passing an undefined/cast integer as AzureStorageRole, e.g. `(AzureStorageRole)999`, to storage.WithRoleAssignments(...) on the non-emulator path.

Common situations: Casting raw ints from config into the enum; consuming an enum value from a different Aspire version that does not exist in the referenced assembly; typo-driven invalid casts.

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Storage/AzureStorageExtensions.cs:789

                AzureStorageRole.StorageAccountBackupContributor => StorageBuiltInRole.StorageAccountBackupContributor,
                AzureStorageRole.StorageAccountContributor => StorageBuiltInRole.StorageAccountContributor,
                AzureStorageRole.StorageAccountKeyOperatorServiceRole => StorageBuiltInRole.StorageAccountKeyOperatorServiceRole,
                AzureStorageRole.StorageBlobDataContributor => StorageBuiltInRole.StorageBlobDataContributor,
                AzureStorageRole.StorageBlobDataOwner => StorageBuiltInRole.StorageBlobDataOwner,
                AzureStorageRole.StorageBlobDataReader => StorageBuiltInRole.StorageBlobDataReader,
                AzureStorageRole.StorageBlobDelegator => StorageBuiltInRole.StorageBlobDelegator,
                AzureStorageRole.StorageFileDataPrivilegedContributor => StorageBuiltInRole.StorageFileDataPrivilegedContributor,
                AzureStorageRole.StorageFileDataPrivilegedReader => StorageBuiltInRole.StorageFileDataPrivilegedReader,
                AzureStorageRole.StorageFileDataSmbShareContributor => StorageBuiltInRole.StorageFileDataSmbShareContributor,
                AzureStorageRole.StorageFileDataSmbShareReader => StorageBuiltInRole.StorageFileDataSmbShareReader,
                AzureStorageRole.StorageFileDataSmbShareElevatedContributor => StorageBuiltInRole.StorageFileDataSmbShareElevatedContributor,
                AzureStorageRole.StorageQueueDataContributor => StorageBuiltInRole.StorageQueueDataContributor,
                AzureStorageRole.StorageQueueDataReader => StorageBuiltInRole.StorageQueueDataReader,
                AzureStorageRole.StorageQueueDataMessageSender => StorageBuiltInRole.StorageQueueDataMessageSender,
                AzureStorageRole.StorageQueueDataMessageProcessor => StorageBuiltInRole.StorageQueueDataMessageProcessor,
                AzureStorageRole.StorageTableDataContributor => StorageBuiltInRole.StorageTableDataContributor,
                AzureStorageRole.StorageTableDataReader => StorageBuiltInRole.StorageTableDataReader,
                _ => throw new ArgumentException($"'{roles[i]}' is not a valid {nameof(AzureStorageRole)} value.", nameof(roles))
            };
        }

        return builder.WithRoleAssignments(target, builtInRoles);
    }

    private static IResourceBuilder<AzureBlobStorageResource> CreateBlobService(IResourceBuilder<AzureStorageResource> builder, string name)
    {
        var resource = new AzureBlobStorageResource(name, builder.Resource);

        string? connectionString = null;

        // Add the "Blobs" resource health check. This is a separate health check from the "Storage" resource health check.
        // Doing it on the storage is not sufficient as the WaitForHealthyAsync doesn't bubble up to the parent resources.
        var healthCheckKey = $"{resource.Name}_check";

        BlobServiceClient? blobServiceClient = null;
        builder.ApplicationBuilder.Services.AddHealthChecks().AddAzureBlobStorage(sp =>

View on GitHub (pinned to 25830f84bd)