dotnet/efcore · error · ArgumentException

Timeout must be less than or equal to Int32.MaxValue (214748

Error message

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

What it means

Thrown by SetCommandTimeout(TimeSpan) when timeout.TotalSeconds exceeds int.MaxValue (2147483647). The ADO.NET CommandTimeout is an int (seconds), so larger spans cannot be represented.

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 dbf9771522)

Solutions

Use a reasonable timeout (e.g. 30-300 seconds) or Timeout.InfiniteTimeSpan for unbounded.
Clamp: TimeSpan.FromSeconds(Math.Min(int.MaxValue, Math.Max(0, seconds))).
Verify the unit of the configured value; convert ms->s when needed.
Prefer the int? overload SetCommandTimeout(int?) to avoid TimeSpan arithmetic overflow.

Example fix

// before
db.Database.SetCommandTimeout(TimeSpan.FromMilliseconds(cfg.TimeoutMs)); // 2147484000ms treated as seconds -> throws

// after
db.Database.SetCommandTimeout(TimeSpan.FromSeconds(cfg.TimeoutMs / 1000.0));
// or simply
db.Database.SetCommandTimeout(cfg.TimeoutSeconds); // int overload

Defensive patterns

Strategy: validation

Validate before calling

if (timeout.TotalSeconds > int.MaxValue)
    throw new ArgumentOutOfRangeException(nameof(timeout));
db.Database.SetCommandTimeout(timeout);
// or clamp:
db.Database.SetCommandTimeout(TimeSpan.FromSeconds(Math.Min(int.MaxValue, timeout.TotalSeconds)));

Type guard

static bool IsValidTimeout(TimeSpan t)
    => t == Timeout.InfiniteTimeSpan || (t >= TimeSpan.Zero && t.TotalSeconds <= int.MaxValue);

Prevention

Prefer the int? SetCommandTimeout overload to avoid TimeSpan arithmetic overflow.
Double-check units (ms vs seconds) in configuration.
Clamp absurd configured values at startup.

When it happens

Trigger: Calling db.Database.SetCommandTimeout(timeSpan) where timeSpan.TotalSeconds > int.MaxValue (RelationalDatabaseFacadeExtensions.cs:970-972). Typically from misconfiguration such as a TimeSpan parsed from an absurd number of days, or a unit confusion (ms vs s).

Common situations: Configuration given in milliseconds but treated as seconds; '999999' style sentinel values; TimeSpan.MaxValue; combining days/hours/mins into a huge span; copying a connection-timeout value into command-timeout.

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@dbf9771522 (2026-08-06). Data as JSON: /api/errors/9eaa92eca854b424. Report an issue: GitHub.