What causes "Count must be between 1 and 250." in microsoft/aspire?

Pass a value between 1 and 250.

microsoft/aspire · error · ArgumentOutOfRangeException

Count must be between 1 and 250.

Error message

Count must be between 1 and 250.

What it means

WithPartitionCount validates that the emulator partition count is between 1 and 250 inclusive; values outside that range throw ArgumentOutOfRangeException including the offending value. The limit reflects the classic Azure Cosmos DB emulator's maximum supported partition count.

Solutions

Pass a value between 1 and 250.
Clamp or validate configuration-derived values before calling the API.
Reduce the desired partition count to the emulator-supported maximum of 250.

Example fix

// before
var count = int.Parse(config["PartitionCount"]); // "0"
cosmos.WithPartitionCount(count);
// after
var count = Math.Clamp(int.Parse(config["PartitionCount"] ?? "10"), 1, 250);
cosmos.WithPartitionCount(count);

Defensive patterns

Strategy: validation

Validate before calling

if (count is < 1 or > 250) throw new ArgumentOutOfRangeException(nameof(count));

Try / catch

try { builder.WithPartitionCount(count); } catch (ArgumentOutOfRangeException) { /* clamp to 1..250 and retry */ }

Prevention

Clamp config-derived counts with Math.Clamp(value, 1, 250).
Never pass 0 or negatives from defaults.
Remember the emulator caps at 250 partitions.

When it happens

Trigger: Calling WithPartitionCount(0), WithPartitionCount(-1), or WithPartitionCount(251) and above.

Common situations: Reading the count from configuration where a default of 0 is used; attempting large values for load testing beyond emulator limits.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

    /// <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.")]
    [Obsolete($"This method is obsolete because it has the wrong return type and will be removed in a future version. Use {nameof(AddCosmosDatabase)} instead to add a Cosmos DB database.")]
    public static IResourceBuilder<AzureCosmosDBResource> AddDatabase(this IResourceBuilder<AzureCosmosDBResource> builder, string databaseName)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(databaseName);

View on GitHub (pinned to 25830f84bd)