dotnet database ai_generated true

Microsoft.Data.SqlClient.SqlException: A network-related or instance-specific error occurred while establishing a connection to SQL Server.

ID: dotnet/sqlexception-connection

Also available as: JSON · Markdown
82%Fix Rate
85%Confidence
80Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
8 active — — —

Root Cause

SqlException connection failure occurs when the application cannot establish a TCP connection to SQL Server. Common causes include incorrect connection strings, firewall rules blocking port 1433, SQL Server not running, or authentication misconfiguration. Fix by verifying connection parameters and network connectivity.

generic

Workarounds

  1. 85% success Verify connection string parameters and network connectivity 
    Check: 1) Server hostname/IP resolves correctly (nslookup/dig), 2) Port 1433 is reachable (telnet server 1433), 3) SQL Server is running (systemctl status mssql-server), 4) Connection string format is correct: 'Server=hostname;Database=dbname;User Id=user;Password=pass;TrustServerCertificate=True;'
  2. 88% success Add TrustServerCertificate=True for development or configure proper SSL certificates 
    For development: add 'TrustServerCertificate=True' to the connection string. For production: install a proper SSL certificate on SQL Server and ensure the CA certificate is trusted by the client machine. This resolves the common 'certificate chain not trusted' variant of connection failures

Dead Ends

Common approaches that don't work:

  1. Switching between Microsoft.Data.SqlClient and System.Data.SqlClient packages 90% fail

    Both packages use the same underlying TDS protocol; if the server is unreachable, switching the client library will not fix network connectivity issues. This only wastes time and can introduce API incompatibilities

  2. Adding Encrypt=False to the connection string to bypass SSL errors 65% fail

    Starting with Microsoft.Data.SqlClient 4.0, Encrypt=True is the default. Disabling encryption is a security risk and may not fix the connection issue if the actual problem is network routing or authentication

Error Chain

Leads to:
Preceded by:
Frequently confused with: