dotnet/efcore · error · InvalidOperationException

The specified 'MinBatchSize' value

Error message

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

What it means

RelationalOptionsExtension.WithMinBatchSize requires null (unset) or a value strictly greater than zero; 0 and negatives are rejected. This sets the threshold below which statements are sent individually rather than grouped.

Solutions

Pass a positive int (>= 1), or leave unset / pass null for the provider default.
Validate config and coerce 0/negative to null.
Ensure MinBatchSize <= MaxBatchSize to avoid later provider complaints.

Example fix

// before
optionsBuilder.UseSqlServer(conn).MinBatchSize(0);

// after
optionsBuilder.UseSqlServer(conn).MinBatchSize(2); // or omit

Defensive patterns

Strategy: validation

Validate before calling

static int? SafeMinBatchSize(string? raw)
    => int.TryParse(raw, out var v) && v > 0 ? v : (int?)null;

Type guard

static bool IsValidMinBatchSize(int? value) => value is null || value > 0;

Prevention

Pass a positive int or leave unset; 0/negative is invalid.
Ensure MinBatchSize does not exceed MaxBatchSize.
Validate config-derived values centrally.

When it happens

Trigger: Calling optionsBuilder.MinBatchSize(0) or a negative; computing MinBatchSize from configuration that resolves to 0.

Common situations: Confusing MinBatchSize with MaxBatchSize; passing 0 intending 'always batch'; mis-parsed config.

Related errors

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

Appendix: 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 3a2006ef56)