A network-related or instance-specific error occurred while establishing a connection to SQL Server

What it means

The client couldn’t open a connection to SQL Server at all, so no login happened and no SQL ran. The long first sentence is the same for every cause; the part in brackets at the end is the clue. On Windows (SqlClient, SSMS) it reads like this:

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 - No such host is known.)

ODBC Driver 18 on Linux (sqlcmd in the SQL Server container, for example) words it slightly differently (“…has occurred while establishing a connection to localhost,1499. Server is not found or not accessible…”) and put the clue in the line before: TCP Provider: Error code 0x2AF9 is 11001 in hex, an unknown host.

Common causes

1. Wrong host or port: a typo, a server that moved, or a port that isn’t the default 1433. SQL Server separates the port with a comma (myserver,1450), not a colon.
2. SQL Server isn’t running, or is still starting.
3. TCP/IP is disabled on the server. Developer and Express editions install with it off, so only local connections work until you enable it.
4. A firewall blocks TCP 1433 (or the instance’s port) between you and the server: Windows Firewall, a cloud security group, a corporate network.
5. A named instance can’t be found: host\INSTANCE needs the SQL Server Browser service answering on UDP 1434 to learn the instance’s port. Browser stopped, UDP 1434 blocked, or a misspelt instance name all give error 26.
6. Docker: the container’s port isn’t published, or is published on a different host port, or you used the container’s internal name from your Mac.
7. Azure SQL Database: your address isn’t allowed by the server’s firewall (error 40615 once the gateway answers), or outbound 1433 is blocked on your network.

How to fix it

Check the name and port from your machine

dscacheutil -q host -a name <host>     # macOS: does the name resolve?
nc -vz <host> 1433                      # is anything listening?

Connection refused means the host is up but nothing listens on that port; a long wait and a timeout means something drops the packets. On the server, the error log says where SQL Server listens:

Server is listening on [ 'any' <ipv4> 1433] accept sockets 1.

Start SQL Server and enable TCP/IP

On Windows, in SQL Server Configuration Manager: SQL Server Services shows whether the instance is running; SQL Server Network Configuration › Protocols for <instance> has TCP/IP, which must be Enabled, then restart the service. Check the instance’s port on the IP Addresses tab (IPAll). On Linux, systemctl status mssql-server, and mssql-conf set network.tcpport for the port.

Open the firewall

Allow inbound TCP 1433 (or the instance’s static port) on the server, and if clients use instance names, UDP 1434 for SQL Server Browser. In the cloud, that’s the security group or network rule in front of the server too.

Named instances: start SQL Server Browser, or skip it

The client asks SQL Server Browser, on UDP port 1434, which TCP port INSTANCE uses. Either make sure the SQL Server Browser service is running and UDP 1434 is reachable, or skip the lookup by giving the port yourself, which works through firewalls that only allow TCP:

myserver,1450

A named instance on dynamic ports can change port when it restarts, so give it a fixed one first (Configuration Manager › TCP/IP › IP Addresses › IPAll › TCP Port). See connecting to a named instance.

Docker: publish the port

docker ps shows the mapping, such as 0.0.0.0:14322->1433/tcp: from your Mac, connect to localhost,14322. If there’s no ->, the port isn’t published: recreate the container with -p 1433:1433 (or another host port). From another container on the same network, use the service name and 1433. See SQL Server in Docker.

Azure SQL Database

Use the full name <server>.database.windows.net and port 1433, allow outbound TCP 1433 on your network, and add your public address to the server’s firewall in the Azure portal (Networking). Rule changes can take up to five minutes. See connecting to Azure SQL Database.

Reproduce it

sqlcmd 18.6 (ODBC Driver 18.6 for SQL Server) inside the SQL Server 2022 container. A port nothing listens on:

sqlcmd -C -S localhost,1499 -U inlet -P <password> -Q "select 1"

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Login timeout expired.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : TCP Provider: Error code 0x2749.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : A network-related or instance-specific error has occurred while establishing a connection to localhost,1499. Server is not found or not accessible. Check if instance name is correct and if SQL Server is configured to allow remote connections. For more information see SQL Server Books Online..

A named instance that doesn’t exist (nothing answers on UDP 1434 there):

sqlcmd -C -S 'localhost\NOSUCH' -U inlet -P <password> -Q "select 1"

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Login timeout expired.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : SQL Server Network Interfaces: Error Locating Server/Instance Specified [xFFFFFFFF]. .
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : A network-related or instance-specific error has occurred while establishing a connection to localhost\NOSUCH. Server is not found or not accessible. Check if instance name is correct and if SQL Server is configured to allow remote connections. For more information see SQL Server Books Online..

A host name that doesn’t exist:

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Login timeout expired.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : TCP Provider: Error code 0x2AF9.
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : A network-related or instance-specific error has occurred while establishing a connection to nosuchhost.invalid. Server is not found or not accessible. …

Each took about eight seconds before sqlcmd gave up, even the refused port. From the Mac, nc -vz 127.0.0.1 1499 said Connection refused at once, and a SQL Server Browser query for an instance, sent to UDP 1434 on 127.0.0.1, got no reply within two seconds: no Browser runs there.

In Inlet

Inlet’s SQL Server driver reports these failures in its own words, and links to this page:

• Couldn’t connect to <host>:<port>: Connection refused (or Operation timed out), for a port nothing answers on or a network that drops the packets.
• Couldn’t find the host “<host>”: …, for a name that doesn’t resolve.
• SQL Server Browser on <host> didn’t say where the instance “<instance>” is (UDP port 1434). Give the instance’s port instead., for a named instance the Browser didn’t answer for.

Inlet connects to named instances as host\INSTANCE, looking the port up from SQL Server Browser, or to a port you give. It can also reach a server through an SSH tunnel, using the system ssh, so your ~/.ssh/config and SSH agent work: useful when port 1433 is only open inside the server’s network.