dotnet/efcore · error · InvalidOperationException

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

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

Set MaxBatchSize to a positive integer (e.g., 10, 42) representing the max statements per batch.

Error message

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

What it means

Thrown by RelationalOptionsExtension.WithMaxBatchSize(int?) at lines 194-197 when the supplied value is <= 0. MaxBatchSize controls how many INSERT/UPDATE/DELETE statements EF groups into a single round-trip during SaveChanges; it must be at least 1 to be meaningful.

Source

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

    /// <summary>
    ///     The maximum number of statements that will be included in commands sent to the database
    ///     during <see cref="DbContext.SaveChanges()" /> or <see langword="null" /> if none has been set.
    /// </summary>
    public virtual int? MaxBatchSize
        => _maxBatchSize;

    /// <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="maxBatchSize">The option to change.</param>
    /// <returns>A new instance with the option changed.</returns>
    public virtual RelationalOptionsExtension WithMaxBatchSize(int? maxBatchSize)
    {
        if (maxBatchSize.HasValue
            && maxBatchSize <= 0)
        {
            throw new InvalidOperationException(RelationalStrings.InvalidMaxBatchSize(maxBatchSize));
        }

        var clone = Clone();

        clone._maxBatchSize = maxBatchSize;

        return clone;
    }

    /// <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.

View on GitHub (pinned to dbf9771522)

Solutions

Set MaxBatchSize to a positive integer (e.g., 10, 42) representing the max statements per batch.
To effectively disable batching, set MaxBatchSize to 1.
Validate config: if (configuredMaxBatchSize > 0) sql.MaxBatchSize(configuredMaxBatchSize);

Example fix

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

// after: positive value, or 1 to disable batching
optionsBuilder.UseSqlServer(connStr, sql => sql.MaxBatchSize(1));

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Validate batch size config values are > 0 before passing to EF.
Treat 0 as 'unset' rather than passing it through.
Document that MaxBatchSize=1 disables batching.

When it happens

Trigger: Calling optionsBuilder.UseSqlServer(connStr, sql => sql.MaxBatchSize(0)) or any negative value. Also occurs when the value comes from a config source that is misconfigured or left at a default sentinel like 0.

Common situations: Reading MaxBatchSize from appsettings with a missing or zero default. Setting it to 0 intending to 'disable batching' (which is actually done by setting it to 1).

Related errors

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