dotnet/efcore · error · ArgumentException

Timeout must be less than or equal to Int32.MaxValue…

Error message

Timeout must be less than or equal to Int32.MaxValue (2147483647) seconds. Provided timeout: {seconds} seconds.

What it means

Thrown by RelationalDatabaseFacadeExtensions.SetCommandTimeout(TimeSpan) when timeout.TotalSeconds exceeds int.MaxValue (2147483647). ADO.NET command timeouts are expressed in whole seconds as int, so values beyond the int range cannot be applied.

Solutions

Cap the timeout at a sane maximum or use Timeout.InfiniteTimeSpan (which the API maps to 0) to mean no limit.
Validate and clamp TotalSeconds to <= int.MaxValue before calling.
Use the int-based SetCommandTimeout(int) overload with a bounded value.

Example fix

// before
context.Database.SetCommandTimeout(TimeSpan.FromDays(9999)); // throws TimeoutTooBig

// after
var ts = TimeSpan.FromDays(1); // a bounded, sane value
context.Database.SetCommandTimeout(ts);

Defensive patterns

Strategy: validation

Validate before calling

TimeSpan ts = configuredTimeout;
if (ts == Timeout.InfiniteTimeSpan)
    context.Database.SetCommandTimeout(0);
else if (ts.TotalSeconds > int.MaxValue)
    throw new ArgumentOutOfRangeException(nameof(configuredTimeout), $"Timeout must be <= {int.MaxValue} seconds.");
else if (ts < TimeSpan.Zero)
    throw new ArgumentOutOfRangeException(nameof(configuredTimeout), "Timeout must be >= 0.");
else
    context.Database.SetCommandTimeout(ts);

Prevention

Bound configured timeouts to a sensible maximum (e.g. hours, not days-in-seconds).
Use Timeout.InfiniteTimeSpan for no-limit rather than enormous values.
Prefer the int-seconds SetCommandTimeout overload with a clamped value.

When it happens

Trigger: Calling Database.SetCommandTimeout(TimeSpan) with a value whose TotalSeconds > int.MaxValue — e.g. TimeSpan.MaxValue, or a multi-century duration from a config typo.

Common situations: Configuration supplying an enormous timeout (days/years) interpreted as seconds; passing Timeout.InfiniteTimeSpan intended as 'no limit' but instead passing a huge TimeSpan; unit tests using arbitrary large values.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at src/EFCore.Relational/Extensions/RelationalDatabaseFacadeExtensions.cs:972

    /// </remarks>
    /// <param name="databaseFacade">The <see cref="DatabaseFacade" /> for the context.</param>
    /// <param name="timeout">The timeout to use.</param>
    public static void SetCommandTimeout(this DatabaseFacade databaseFacade, TimeSpan timeout)
    {
        if (timeout == Timeout.InfiniteTimeSpan)
        {
            databaseFacade.SetCommandTimeout(0);
            return;
        }

        if (timeout < TimeSpan.Zero)
        {
            throw new ArgumentException(RelationalStrings.TimeoutTooSmall(timeout.TotalSeconds));
        }

        if (timeout.TotalSeconds > int.MaxValue)
        {
            throw new ArgumentException(RelationalStrings.TimeoutTooBig(timeout.TotalSeconds));
        }

        databaseFacade.SetCommandTimeout(Convert.ToInt32(timeout.TotalSeconds));
    }

    /// <summary>
    ///     Returns the timeout (in seconds) set for commands executed with this <see cref="DbContext" />.
    /// </summary>
    /// <remarks>
    ///     <para>
    ///         Note that the command timeout is distinct from the connection timeout, which is commonly
    ///         set on the database connection string.
    ///     </para>
    ///     <para>
    ///         See <see href="https://aka.ms/efcore-docs-connections">Connections and connection strings</see> for more information and examples.
    ///     </para>
    /// </remarks>
    /// <param name="databaseFacade">The <see cref="DatabaseFacade" /> for the context.</param>

View on GitHub (pinned to 3a2006ef56)