The Error

App crashes on first DB query:

Microsoft.Data.SqlClient.SqlException: A network-related or instance-specific error occurred while establishing a connection to SQL Server. 
The server was not found or was not accessible.

Quick Fix - 2 Minutes

Check connection string + SQL Server config. 90% of cases:

// appsettings.json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=MyDb;Trusted_Connection=True;TrustServerCertificate=True;"
  }
}

Step-by-Step: How to Debug

Can SSMS connect?: If SQL Server Management Studio fails too, it's not your app
Check SQL Server service: services.msc > SQL Server (MSSQLSERVER) must be Running
Check TCP/IP: SQL Server Config Manager > Network Config > Enable TCP/IP
Check firewall: Port 1433 must be open
Docker/SQL Express: Use Server=localhost,1433 or Server=localhost\SQLEXPRESS

Common Scenarios

LocalDB: Use Server=(localdb)\mssqllocaldb;Database=MyDb;
Docker: Use Server=host.docker.internal,1433 from container
Azure SQL: Add your IP to firewall rules. Use Server=tcp:myserver.database.windows.net,1433;
TrustServerCertificate: Required for local dev with self-signed certs

Real-World Scenario: Connection Works Locally, Fails in Docker

#1 most upvoted StackOverflow issue. Your app connects fine in Visual Studio but fails in Docker:

# docker-compose.yml
services:
  webapp:
    build: .
    environment:
      - ConnectionStrings__Default=Server=sqlserver;Database=MyDb;User Id=sa;Password=YourStrong@Passw0rd;TrustServerCertificate=True
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong@Passw0rd
    ports:
      - "1433:1433"

3 fixes required:

Server name: Use sqlserver not localhost. Docker uses service names for DNS.
TrustServerCertificate=True: Docker SQL uses self-signed cert. Without this you get SSL errors.
Health check: App starts before SQL is ready. Add depends_on with healthcheck or use retry logic.

Related Fixes You Should Know

SQL connection errors trigger these next:

Docker Connection Refused ASP.NET - App in Docker can't reach SQL. Usually localhost vs host.docker.internal issue.
EF Core Migration Pending - App connects but DB doesn't exist. Run dotnet ef database update or context.Database.Migrate().
Kestrel Certificate Not Found - HTTPS + SQL both fail with cert errors. Dev certs not trusted.
Azure SQL Connection Failed - Works local, fails on Azure. You forgot to whitelist App Service IP in Azure SQL firewall.

FAQ

Q: What does "TrustServerCertificate=True" do?

Skips SSL cert validation. Required for SQL Server with self-signed certs like LocalDB, Docker, SQL Express. Never use in production. Use proper CA-signed certs instead.

Q: Why does SQL Server work in SSMS but not my.NET 8 app?

SSMS uses Named Pipes by default. .NET uses TCP/IP. Enable TCP/IP in SQL Server Configuration Manager > SQL Server Network Configuration > Protocols for MSSQLSERVER.

Best Practice for.NET 8

Add retry logic. Azure SQL has transient faults:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(connectionString, sqlOptions =>
    {
        sqlOptions.EnableRetryOnFailure(
            maxRetryCount: 5,
            maxRetryDelay: TimeSpan.FromSeconds(30),
            errorNumbersToAdd: null);
    }));

Fix: Unable to connect to SQL Server database