How do I fix the Mysql error “Connection refused”?

The MySQL server error SQLSTATE[HY000] [2002] Connection refused. can be caused by several reasons, if you follow the steps below you should be able to fix this issue:

  • Check that your config file config/config.ini.php (in the Matomo directory) contains the correct and up to date DB credentials under the [database] section. Check that the DB username, DB password, database host, and database port are correct. (if you are unsure, reach out to your database administrator or check in your web hosting account for the up to date credentials).
  • If the config file references host = "localhost", you can try to change it to 127.0.0.1 instead, for example in your config.ini.php under [database] set host = "127.0.0.1".
  • If the above changes do not resolve the issue, we recommend you try to connect to MySQL on the command line to check if the credentials are correct and the server works. Connect to the server running Matomo and run this command: mysql -h [hostname] -u [username] -p[password] -D [dbname] (and replace the parameters in [] by the values found in your config.ini.php file.).
  • If the command above works, but you still get the “Connection refused” error in the browser, there may be an issue with PHP. Please reach out to your web hosting company or system administrator.
  • Check that the MySQL Server is running. Connect to the server running the MySQL database and check if the MySQL server is actively running by running this command mysqladmin -u root -p status (which should return an output like this: Uptime: 172505 Threads: 2 Questions: 90 Slow queries: 0 Opens: 157 Flush tables: 3 Open tables: 76)
  • If you find the DB server is not running, proceed to restart Mysql server (or rebooting the whole server).
  • Or If the Database server have run out of disk space and there is no space left on the server, it may also start to refuse connections.
  • Sometimes MySQL servers are configured to refused some connections (for example connections from outside the network). If your MySQL database is managed by your web hosting company, contact them as they may be able to help.

If you still have the SQLSTATE[HY000] [2002] Connection refused. after checking the steps above, feel free to reach out to us by clicking the feedback button below.

Previous FAQ: How do I fix the error “Mysql Server has gone away”?