Built-in retry logic providers in SqlClient

Applies to: .NET Framework .NET .NET Standard

Download ADO.NET

Microsoft.Data.SqlClient.SqlConfigurableRetryFactory creates providers for common retry schedules. Configurable retry logic is off by default. Assign a provider to SqlConnection.RetryLogicProvider or SqlCommand.RetryLogicProvider to enable it for that object.

Choose a retry provider

The fixed, incremental, and exponential providers add random jitter to each interval. Jitter reduces synchronized retry bursts when many clients encounter the same outage.

NumberOfTries is the total number of attempts, including the initial operation. For example, NumberOfTries = 3 allows the initial attempt and up to two retries. Its valid range is 1 through 60.

Built-in transient error list

When SqlRetryLogicOption.TransientErrors is null, the built-in providers retry the 20 error numbers in SqlConfigurableRetryFactory.BaselineTransientErrors, grouped by where the failure originates:

Each error is described in the sections that follow.

In Microsoft.Data.SqlClient 7.0, SqlConfigurableRetryFactory.BaselineTransientErrors exposes the built-in list as a read-only collection. Use it to extend the baseline without copying error numbers from the driver source:

var transientErrors = SqlConfigurableRetryFactory.BaselineTransientErrors
    .Append(12345)
    .ToArray();

var options = new SqlRetryLogicOption
{
    NumberOfTries = 5,
    DeltaTime = TimeSpan.FromSeconds(2),
    MaxTimeInterval = TimeSpan.FromSeconds(30),
    TransientErrors = transientErrors,
};

For earlier driver versions, create an application-owned collection that contains the baseline errors you need and your additional errors. Before copying a baseline, select the SqlClient source tag that matches your installed package version and inspect SqlConfigurableRetryFactory.cs. The list on the main branch can change after your package is released.

Errors during connection establishment

The following errors are retryable in the built-in list or worth adding to TransientErrors on top of the built-in list.

The following errors can be transient when they occur during connection establishment or while sending a request to the server. Retry on a short, bounded backoff. Errors that persist past a few retries usually indicate a configuration problem, such as a wrong server, missing permissions, incompatible encryption settings, or exhausted quota, that retry won't fix.

Statement-level errors aren't in this list because they fire after the connection is established and the failure leaves the session usable. The most common retryable statement errors are 1205 (deadlock victim) and 1222 (lock-request timeout). Retry the entire transaction rather than the single failing statement.

Error message text is from Azure SQL transient connection errors. These errors are eligible for retry across SQL Server, Azure SQL Database, Azure SQL Managed Instance, SQL database in Microsoft Fabric, and dedicated SQL pools in Azure Synapse Analytics.

Errors during command execution

The following errors occur after a connection is established, while a command is executing. Retry the whole transaction, not the individual statement. Retrying one statement inside a transaction can duplicate earlier work or violate the transaction's ordering guarantees.

Statement-level errors that reflect a batch or schema problem (for example, 102 syntax errors, 207 invalid column, 2812 missing stored procedure) aren't transient. Fix the query text or the schema binding; retry doesn't help.

Error message text is from the sys.messages catalog view. These errors come from the SQL Server engine, so their numbers are the same across SQL Server, Azure SQL Database, Azure SQL Managed Instance, SQL database in Microsoft Fabric, and dedicated SQL pools in Azure Synapse Analytics, regardless of driver.

The driver, not the engine, surfaces client-side representations of statement timeout and cancellation errors (for example, the Microsoft.Data.SqlClient -2 timeout), so these errors aren't in the built-in list. If your application catches these errors separately, handle them at the same transaction boundary as the engine errors described earlier.

Command and transaction behavior

The built-in providers skip retry when a command runs inside an ambient TransactionScope or has a SqlTransaction attached. The command runs once without retry logic. Retrying a single statement inside a transaction can duplicate earlier work or violate the transaction's intended ordering.

Use SqlRetryLogicOption.AuthorizedSqlCondition to limit command retries to operations your application can safely repeat. The predicate receives the command text. If the predicate returns false, the command runs once without retry logic.

Example

For complete connection and command examples, see:

• SqlConnection.RetryLogicProvider
• SqlCommand.RetryLogicProvider

Related content

• Create a custom retry provider for SqlClient
• Configurable retry logic in SqlClient
• Microsoft.Data.SqlClient for SQL Server