Microsoft.Data.SqlClient.SqlException

A SqlException is thrown when SQL Server, or the driver in front of it, reports an error. It covers everything from a server that cannot be reached, to a query that has a syntax error, to a deadlock.

The message has the text, but the Number property is the one to use in code. It is the error number of SQL Server, such as 18456 for a failed login and 1205 for a deadlock, and the same number always has the same meaning.

Statistics

28

3

Common causes

The error number sorts the problems. These are the ones that you meet most often.

using var connection = new SqlConnection("Server=localhost,1;Database=Shop;Integrated Security=true;Connect Timeout=2;Encrypt=false");
connection.Open();   // SqlException

using var connection = new SqlConnection("Server=localhost,1;Database=Shop;Integrated Security=true;Connect Timeout=2;Encrypt=false");

try
{
    connection.Open();
}
catch (SqlException e) when (e.Number is -2 or 53 or 258)
{
    logger.LogWarning(e, "The database is not available");
}

Server=tcp:myserver.database.windows.net,1433;Database=Shop;User ID=shop_app;Password=<secret>;Encrypt=True;

public async Task<int> CountAsync(SqlConnection connection)
{
    using var command = new SqlCommand("SELECT COUNT(*) FROM Orders", connection);
    command.CommandTimeout = 120;
    return (int)await command.ExecuteScalarAsync();
}

public async Task SaveAsync(SqlConnection connection)
{
    for (var attempt = 1; attempt <= 3; attempt++)
    {
        try
        {
            using var command = new SqlCommand("UPDATE Orders SET Status = 1", connection);
            await command.ExecuteNonQueryAsync();
            break;
        }
        catch (SqlException e) when (e.Number == 1205 && attempt < 3)
        {
            await Task.Delay(100 * attempt);
        }
    }
}

How to fix it and prevent it

try
{
    using var connection = new SqlConnection("Server=localhost,1;Database=Shop;Integrated Security=true;Connect Timeout=2;Encrypt=false");
    connection.Open();
}
catch (SqlException e)
{
    var message = e.Number switch
    {
        2601 or 2627 => "That value already exists.",
        547 => "The item is still in use.",
        1205 => "The database was busy, try again.",
        _ => "Database error " + e.Number
    };

    Console.WriteLine(message);
}

Server=tcp:myserver.database.windows.net,1433;Database=Shop;ConnectRetryCount=3;ConnectRetryInterval=10;

How to read the stack trace

The first line has the error number and the message. The frames in Microsoft.Data.SqlClient are the driver, and the first line in your code is the call that opened the connection or ran the command:

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: TCP Provider, error: 0 - The wait operation timed out.)
 ---> System.ComponentModel.Win32Exception (258): The wait operation timed out.
   at Microsoft.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection, Action`1 wrapCloseInAction)
   at Microsoft.Data.SqlClient.TdsParser.ThrowExceptionAndWarning(TdsParserStateObject stateObj, SqlCommand command, Boolean callerHasConnectionLock, Boolean asyncClose)
   at Microsoft.Data.SqlClient.TdsParser.Connect(ServerInfo serverInfo, SqlInternalConnectionTds connHandler, TimeoutTimer timeout, SqlConnectionString connectionOptions, Boolean withFailover)
   at Microsoft.Data.SqlClient.SqlConnection.TryOpen(TaskCompletionSource`1 retry, SqlConnectionOverrides overrides)
   at Microsoft.Data.SqlClient.SqlConnection.Open(SqlConnectionOverrides overrides)
   at Microsoft.Data.SqlClient.SqlConnection.Open()
   at Shop.Services.CustomerRepository.Count() in C:\src\Shop\Services\CustomerRepository.cs:line 17
   at Program.<Main>$(String[] args) in C:\src\Shop\Program.cs:line 4
ClientConnectionId:6f0c1f4e-3b8a-4c53-9d0e-5a9d2c1b7e42
Error Number:258,State:0,Class:20

The error number is 0x80131904, the general code, and the message says that the server could not be reached. The inner Win32Exception (258) is a timeout of the connection attempt. The call is connection.Open() on line 17 of CustomerRepository.cs, so look at the server name, the network and the firewall, and not at the query. The last lines have the Error Number as the driver sees it, and the ClientConnectionId that you can give to Azure support.

Should you catch it?

Yes. A database is a remote system, and it can fail in ways that you cannot check first. Catch SqlException around the call, filter on Number, and handle the errors that you know. Retry the transient ones, and let the others pass.

Do not show the message to users. It can contain the server name and other details that should stay on the server.

Related exceptions

• TimeoutException is thrown when a time limit set in code is reached.
• SocketException is thrown for errors on the network connection.
• InvalidOperationException is thrown when the connection pool is out of connections.

Frequently asked questions

Let your AI agent track it down

Connect Claude Code, Cursor, VS Code or Visual Studio to the elmah.io MCP server and ask your agent to look into SqlException for you. For example:

The agent reads the stack trace and request details from elmah.io, finds the code in your repository and proposes a fix. In Claude Code, add the server with one command:

claude mcp add --transport http --client-id claudecode elmahio https://mcp.elmah.io/mcp

The MCP server is included on every plan and is currently in beta. Set up the MCP server.

Further reading

YouTube videos

Answers from Stack Overflow

SELECT compatibility_level
FROM sys.databases
WHERE name = 'mydbname';

opts
   .UseSqlServer(@"<CONNECTION STRING>", o => o.UseCompatibilityLevel(110)) // or 150

switch (ex) 
{
    case  System.Data.SqlClient.SqlException exc:
        HandleOldException(exc);
        return true;
    case Microsoft.Data.SqlClient.SqlException exc:
        HandleNewException(exc);
        return true;
    case DbException exc:
        HandleDbException(exc);
        return true;
    default:
        return false;
}

var configuration = new MapperConfiguration(cfg => {
    cfg.CreateMap<System.Data.SqlClient.SqlException, MySqlException>();
    cfg.CreateMap<System.Data.SqlClient.SqlError, MySqlError>();
    cfg.CreateMap<Microsoft.Data.SqlClient.SqlException, MySqlException>();
    cfg.CreateMap<Microsoft.Data.SqlClient.SqlError, MySqlError>();
});

var commonExp=mapper.Map<MySqlException>(ex);

Source: Stack Overflow