dotnet/efcore · error · InvalidOperationException

The specified 'MinBatchSize' value '{value}' is not valid. I

Q: What causes "The specified 'MinBatchSize' value '{value}' is not valid. It must be a positive number." in dotnet/efcore?

Set MinBatchSize to a positive integer (typically 2 or higher; 1 means batch even single statements).

Error message

The specified 'MinBatchSize' value '{value}' is not valid. It must be a positive number.

What it means

Thrown by RelationalOptionsExtension.WithMinBatchSize(int?) at lines 222-225 when the supplied value is <= 0. MinBatchSize is the threshold below which EF sends statements individually instead of batching them; it must be at least 1.

Source

Thrown at src/EFCore.Relational/Infrastructure/RelationalOptionsExtension.cs:225

    /// <summary>
    ///     The minimum number of statements that are needed for a multi-statement command sent to the database
    ///     during <see cref="DbContext.SaveChanges()" /> or <see langword="null" /> if none has been set.
    /// </summary>
    public virtual int? MinBatchSize
        => _minBatchSize;

    /// <summary>
    ///     Creates a new instance with all options the same as for this instance, but with the given option changed.
    ///     It is unusual to call this method directly. Instead use <see cref="DbContextOptionsBuilder" />.
    /// </summary>
    /// <param name="minBatchSize">The option to change.</param>
    /// <returns>A new instance with the option changed.</returns>
    public virtual RelationalOptionsExtension WithMinBatchSize(int? minBatchSize)
    {
        if (minBatchSize.HasValue
            && minBatchSize <= 0)
        {
            throw new InvalidOperationException(RelationalStrings.InvalidMinBatchSize(minBatchSize));
        }

        var clone = Clone();

        clone._minBatchSize = minBatchSize;

        return clone;
    }

    /// <summary>
    ///     Indicates whether or not to use relational database semantics when comparing null values. By default,
    ///     Entity Framework will use C# semantics for null values, and generate SQL to compensate for differences
    ///     in how the database handles nulls.
    /// </summary>
    public virtual bool UseRelationalNulls
        => _useRelationalNulls;

    /// <summary>

View on GitHub (pinned to dbf9771522)

Solutions

Set MinBatchSize to a positive integer (typically 2 or higher; 1 means batch even single statements).
Validate the config value before passing: if (configuredMinBatchSize > 0) sql.MinBatchSize(configuredMinBatchSize);

Example fix

// before
optionsBuilder.UseSqlServer(connStr, sql => sql.MinBatchSize(0));

// after
optionsBuilder.UseSqlServer(connStr, sql => sql.MinBatchSize(4));

Defensive patterns

Strategy: validation

Validate before calling

var minBatch = configuration.GetValue<int?>("MinBatchSize");
if (minBatch.HasValue && minBatch <= 0) throw new ArgumentOutOfRangeException(nameof(minBatch), "MinBatchSize must be > 0");
optionsBuilder.UseSqlServer(connStr, sql => { if (minBatch > 0) sql.MinBatchSize(minBatch.Value); });

Prevention

Validate min batch size config values are > 0 before passing.
Use a shared helper to validate all integer EF options from configuration.

When it happens

Trigger: Calling optionsBuilder.UseSqlServer(connStr, sql => sql.MinBatchSize(0)) or a negative value. Also from misconfigured configuration files or environment variables.

Common situations: Reading MinBatchSize from config with a 0 default. Confusing MinBatchSize with MaxBatchSize and setting it to 0 thinking it disables the minimum threshold.

Related errors

AI-assisted analysis of dotnet/efcore@dbf9771522 (2026-08-06). Data as JSON: /api/errors/75017b70f5700cae. Report an issue: GitHub.