microsoft/aspire · error · NotSupportedException

' ' does not work when using the Linux-based (vNext) Azure…

Error message

'{WithPartitionCount}' does not work when using the Linux-based (vNext) Azure Cosmos DB emulator.

What it means

WithPartitionCount configures the classic Windows emulator via the AZURE_COSMOS_EMULATOR_PARTITION_COUNT environment variable, but the Linux-based vNext emulator does not support this setting. Calling WithPartitionCount on a resource configured with RunAsVNextEmulator throws NotSupportedException by design.

Solutions

1. Remove the WithPartitionCount call when using RunAsVNextEmulator; the vNext emulator does not expose this knob.
2. Keep WithPartitionCount only for the classic emulator path (RunAsEmulator without vNext).
3. Check builder.Resource.InnerResource.IsVNextEmulator at runtime and apply the call conditionally.

Example fix

// before
builder.AddAzureCosmosDB("cosmos").RunAsVNextEmulator().WithPartitionCount(10);
// after
builder.AddAzureCosmosDB("cosmos").RunAsVNextEmulator(); // partition count not configurable on vNext

if (builder.Resource.InnerResource.IsVNextEmulator) { /* skip WithPartitionCount */ }

try { builder.WithPartitionCount(10); } catch (NotSupportedException) { /* vNext emulator: knob unsupported, ignore */ }

When it happens

Trigger: Calling RunAsVNextEmulator() followed by WithPartitionCount(n) on the same builder (IsVNextEmulator is true).

Common situations: Migrating an app host from the classic Windows emulator to the vNext Linux emulator while keeping existing emulator tuning calls in place.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ConnectionStringAvailableEvent was published for the
• CosmosClient is not initialized.
• Count must be between 1 and 250.
• The Data Explorer endpoint is only available when using the…
• Value cannot be null. (Parameter 'innerResource')

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs:325

    }

    /// <summary>
    /// Configures the partition count for the Azure Cosmos DB emulator.
    /// </summary>
    /// <param name="builder">Builder for the Cosmos emulator container</param>
    /// <param name="count">Desired partition count.</param>
    /// <returns>Cosmos emulator resource builder.</returns>
    /// <remarks>Not calling this method will result in the default of 10 partitions. The actual started partitions is always one more than specified.
    /// See <a href="https://learn.microsoft.com/azure/cosmos-db/emulator-windows-arguments#change-the-number-of-default-containers">this documentation</a> about setting the partition count.
    /// </remarks>
    [AspireExport]
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithPartitionCount(this IResourceBuilder<AzureCosmosDBEmulatorResource> builder, int count)
    {
        ArgumentNullException.ThrowIfNull(builder);

        if (builder.Resource.InnerResource.IsVNextEmulator)
        {
            throw new NotSupportedException($"'{nameof(WithPartitionCount)}' does not work when using the Linux-based (vNext) Azure Cosmos DB emulator.");
        }

        if (count < 1 || count > 250)
        {
            throw new ArgumentOutOfRangeException(nameof(count), count, "Count must be between 1 and 250.");
        }

        return builder.WithEnvironment("AZURE_COSMOS_EMULATOR_PARTITION_COUNT", count.ToString(CultureInfo.InvariantCulture));
    }

    /// <summary>
    /// Adds a database to the associated Cosmos DB account resource.
    /// </summary>
    /// <param name="builder">AzureCosmosDB resource builder.</param>
    /// <param name="databaseName">Name of database.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <remarks>This method is not available in polyglot app hosts. Use <see cref="AddCosmosDatabase"/> instead.</remarks>
    [AspireExportIgnore(Reason = "Obsolete API with incorrect return type. Use AddCosmosDatabase instead.")]

View on GitHub (pinned to 25830f84bd)