PHP cannot connect to SQL Server through FreeTDS
Adaptive Server is unavailable or does not existShort answer
FreeTDS prints this when it cannot open a session with the server name you gave it. Test the layers in order with the FreeTDS tools: can the host be reached, does the port answer, and does the servername resolve through freetds.conf. The failing step tells you whether it is the network, the port, the config file or the named instance.
Fix it fast
1Find out which cause you have
Skip PHP and test with FreeTDS's own tsql tool, first by host and port, then by servername. The first test that fails is your cause.
tsql -H db.example.com -p 1433 -U myuser tsql -S myserver -U myuser2Match what you see, then jump to its fix
- 1
tsql -H host -p port fails, or telnet to the port answers Connection RefusedThe host is unreachable or the port is wrongFix - 2
tsql -H works but tsql -S myserver failsfreetds.conf is not found, or the servername is not in itFix - 3
the server is addressed as HOST\INSTANCE and no fixed port is knownA named instance needs the instance option, and port and instance cannot be used togetherFix
- 1
What does the error look like?
Adaptive Server is unavailable or does not existConnection Refused
Cause 1 of 3
The host is unreachable or the port is wrong
1Check
FreeTDS's guide says to ping the host, then telnet to the port. Connection Refused means a wrong host, a wrong port, or a server that is down. A Login Failed reply instead means connectivity is fine.
ping -c 3 db.example.com
telnet db.example.com 14332Fix
Correct the host and port, start the SQL Server service, and open the port in any firewall between the two machines.
TDSVER=auto tsql -H db.example.com -p 1433 -U myuser3Verify
tsql prompts for the password or shows Login Failed, which means the connection itself works.
tsql -H db.example.com -p 1433 -U myuserConfirmed by freetds.org
Cause 2 of 3
freetds.conf is not found, or the servername is not in it
1Check
FreeTDS reads the user's .freetds.conf first, then the system-wide freetds.conf, and the FREETDSCONF variable can point at another file. If the servername is missing or the wrong file is read, the lookup fails.
echo "$FREETDSCONF"
ls -l ~/.freetds.conf /etc/freetds/freetds.conf2Fix
Add a section for the servername with host, port and tds version, in the file that tsql -C reports.
[myserver]
host = db.example.com
port = 1433
tds version = auto3Verify
The servername test now connects.
tsql -S myserver -U myuserConfirmed by freetds.org
Cause 3 of 3
A named instance needs the instance option, and port and instance cannot be used together
1Check
The guide says the instance option makes FreeTDS find the port by itself, but it needs UDP access to port 1434 on the server. It is mutually exclusive with port.
nc -zvu db.example.com 14342Fix
Use instance without port, and allow UDP 1434 through the firewall. Or drop instance and give the instance's fixed TCP port in port.
[myserver]
host = db.example.com
instance = SQLEXPRESS
tds version = auto3Verify
Connect by servername.
tsql -S myserver -U myuserConfirmed by freetds.org
How do I stop it coming back?
- Keep one freetds.conf and note its path, so nobody edits a copy that is never read.
- Put the working tsql command in your deployment notes; it is the fastest connection test.
- Prefer a fixed TCP port for the SQL Server instance on servers behind firewalls.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Databases
The client cannot reach the MySQL or MariaDB server through its Unix socket file
ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2) (MariaDB client wording)
Error 2002 means the client tried the Unix socket file named in the message and found nothing it could talk to.
4 causes, each with a fixDatabases
PHP throws "could not find driver" when it opens a PDO connection
Fatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12
PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded.
4 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fix