Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PHP cannot connect to SQL Server through FreeTDS

ErrorAdaptive Server is unavailable or does not exist

Short 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.

  • Applies to FreeTDS 1.x, PHP 8.3, SQL Server, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 myuser
  2. 2Match what you see, then jump to its fix

    1. 1tsql -H host -p port fails, or telnet to the port answers Connection RefusedThe host is unreachable or the port is wrongFix
    2. 2tsql -H works but tsql -S myserver failsfreetds.conf is not found, or the servername is not in itFix
    3. 3the 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

What does the error look like?

  • Adaptive Server is unavailable or does not exist
  • Connection 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 1433

2Fix

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 myuser

3Verify

tsql prompts for the password or shows Login Failed, which means the connection itself works.

tsql -H db.example.com -p 1433 -U myuser

Confirmed by freetds.org

Did this fix it?

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.conf

2Fix

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 = auto

3Verify

The servername test now connects.

tsql -S myserver -U myuser

Confirmed by freetds.org

Did this fix it?

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 1434

2Fix

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 = auto

3Verify

Connect by servername.

tsql -S myserver -U myuser

Confirmed by freetds.org

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.