Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

PHP cannot connect to MySQL: the connection attempt failed

ErrorCan't connect to MySQL server on 'host'

Short answer

Error 2003 means the TCP connection to MySQL never opened. Test the host and port with mysqladmin first. The server is down, the host or port in your PHP code is wrong, MySQL is set to listen on the local machine only, or a firewall drops the traffic.

  • Applies to MySQL 8.4, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Try to reach the server from the same machine that runs PHP, using the same host and port your code uses.

    mysqladmin -h 127.0.0.1 --port=3306 version
  2. 2Match what you see, then jump to its fix

    1. 1The test above is refused, and no mysqld process existsThe MySQL server is not runningFix
    2. 2mysqladmin works with one port, but PHP uses anotherThe host or port in the PHP code is wrongFix
    3. 3Connecting from the server itself works, from another computer failsThe server listens on the local machine onlyFix
    4. 4Local tests pass, remote ones hang or are refused, and bind_address is fineA firewall blocks port 3306Fix

What does the error look like?

  • Can't connect to MySQL server on 'host'
  • Error 2003

Cause 1 of 4

The MySQL server is not running

1Check

Look for the server process.

ps xa | grep mysqld

2Fix

Start the server. The service is named mysql on Debian and Ubuntu, and mysqld on RPM-based systems such as RHEL. On Windows, start the MySQL service from the Services app.

sudo systemctl start mysql

3Verify

The mysqladmin test now prints the server version.

mysqladmin -h 127.0.0.1 --port=3306 version

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 4

The host or port in the PHP code is wrong

1Check

Read the port the server uses from its own variable, then compare it to your connection settings.

mysql -u root -p -e "SHOW VARIABLES LIKE 'port'"

2Fix

Put the same host and port in the PHP connection.

$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=app', $user, $pass);

3Verify

The script connects without an exception.

php -r '$p = new PDO("mysql:host=127.0.0.1;port=3306", "root", ""); echo "ok";'

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 4

The server listens on the local machine only

1Check

A bind_address of 127.0.0.1 accepts only local connections, and skip_networking disables TCP/IP entirely.

mysql -u root -p -e "SHOW VARIABLES LIKE 'bind_address'; SHOW VARIABLES LIKE 'skip_networking'"

2Fix

Set bind_address to an address the other machine can reach, and keep skip_networking off, then restart MySQL. Open access only to trusted hosts.

# in the [mysqld] section of the server config
bind_address = 0.0.0.0

3Verify

From the other machine, the same mysqladmin test with the server address works.

mysqladmin -h SERVER_IP --port=3306 version

Confirmed by dev.mysql.com

Did this fix it?

Cause 4 of 4

A firewall blocks port 3306

1Check

Check iptables or similar rules on Linux, and Windows Firewall or security software on Windows. A refusal on telnet means nothing listens on the port.

telnet SERVER_IP 3306

2Fix

Allow inbound TCP on the MySQL port only from the machines that need it.

# add an allow rule for the client IP on port 3306 in your firewall tool

3Verify

The telnet test connects.

telnet SERVER_IP 3306

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Keep MySQL on a private network or tunnel it; do not expose 3306 to the whole internet.
  • Store the host and port in one config file that the app and your tools both read.
  • Monitor that the mysqld process is up.

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

Laravel bulk insert fails with 'too many placeholders'

SQLSTATE[HY000]: General error: 1390 Prepared statement contains too many placeholders

Laravel sends one placeholder per value, so one insert of many rows times many columns, or a whereIn with a huge list, creates a statement MySQL refuses.

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