PHP cannot connect to MySQL: the connection attempt failed
Can'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.
Fix it fast
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 version2Match what you see, then jump to its fix
- 1
The test above is refused, and no mysqld process existsThe MySQL server is not runningFix - 2
mysqladmin works with one port, but PHP uses anotherThe host or port in the PHP code is wrongFix - 3
Connecting from the server itself works, from another computer failsThe server listens on the local machine onlyFix - 4
Local tests pass, remote ones hang or are refused, and bind_address is fineA firewall blocks port 3306Fix
- 1
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 mysqld2Fix
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 mysql3Verify
The mysqladmin test now prints the server version.
mysqladmin -h 127.0.0.1 --port=3306 versionConfirmed by dev.mysql.com
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
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.03Verify
From the other machine, the same mysqladmin test with the server address works.
mysqladmin -h SERVER_IP --port=3306 versionConfirmed by dev.mysql.com
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 33062Fix
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 tool3Verify
The telnet test connects.
telnet SERVER_IP 3306Confirmed by dev.mysql.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
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 fixDatabases
Laravel query fails: conversion from one collation into another is impossible
SQLSTATE[HY000]: General error: 3988 Conversion from collation utf8_unicode_ci into utf8mb4_0900_ai_ci impossible for parameter
MySQL is comparing or binding a value whose character set cannot be converted into the one on the other side.
3 causes, each with a fixDatabases
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
MySQL or MariaDB: Column count of mysql.proc is wrong, table probably corrupted
Error 1558: Column count of mysql.proc is wrong
The mysql.proc system table has a different number of columns than the running server expects.
3 causes, each with a fixDatabases
Saving an empty date from PHP into a MySQL DATETIME column fails
The column holds 0000-00-00 00:00:00 instead of NULL
An empty string is not NULL.
4 causes, each with a fixDatabases
Laravel migration fails on managed MySQL because a table has no primary key
Add a primary key to the table or unset this variable to avoid this message.
The server has sql_require_primary_key switched on, so every CREATE TABLE or ALTER TABLE must leave the table with a primary key.
3 causes, each with a fix