📋

Description

This error indicates that the MySQL client failed to establish a connection to the MySQL server using the TCP/IP protocol. It typically occurs when the client application attempts to connect to a server that is unreachable, misconfigured, or blocked by network restrictions.

💬

Error Message

Failed to connect to MySQL server on '%s' via TCP/IP

🔍

Known Causes

4 known causes

⚠️

MySQL Server Offline

The MySQL server process is not running or has crashed, making it impossible for clients to establish a connection.

⚠️

Incorrect Connection Parameters

The client application is attempting to connect using the wrong hostname, IP address, or port number for the MySQL server.

⚠️

Firewall Blockage

A firewall (on the server, client, or network path) is preventing the client from establishing a TCP/IP connection to the MySQL server's port.

⚠️

Network Connectivity Issues

Underlying network problems, such as a disconnected cable, routing issues, or DNS resolution failures, prevent communication between client and server.

🛠️

Solutions

4 solutions available

1. Verify MySQL Server Status and Network Reachability easy

Ensures the MySQL server is running and accessible from the client machine.

1

Check if the MySQL server process is running on the server machine.

sudo systemctl status mysql

2

If not running, start the MySQL service.

sudo systemctl start mysql

3

From the client machine, attempt to ping the MySQL server's IP address or hostname.

ping <mysql_server_ip_or_hostname>

4

If ping fails, investigate network connectivity issues between the client and server (firewalls, routing).

text

5

Attempt to connect to the MySQL server using the `mysql` command-line client from the server itself to rule out local connection issues.

mysql -u <username> -p

2. Confirm MySQL Server is Listening on the Correct IP Address and Port medium

Ensures MySQL is configured to accept connections from the network and on the expected port.

1

Log in to the MySQL server and check the `bind-address` configuration in the MySQL configuration file (e.g., `my.cnf` or `my.ini`).

text

2

The `bind-address` should be set to `0.0.0.0` (to listen on all network interfaces) or the specific IP address of the interface you want to use for connections. If it's set to `127.0.0.1`, it will only accept local connections.

text

3

Verify the `port` setting in the MySQL configuration file. The default is `3306`.

text

4

After changing the configuration file, restart the MySQL server for changes to take effect.

sudo systemctl restart mysql

5

On the server, use `netstat` or `ss` to confirm that MySQL is listening on the configured IP and port.

sudo netstat -tulnp | grep mysql

3. Check MySQL User Permissions for Remote Access medium

Ensures the MySQL user you are trying to connect with has the necessary privileges to connect from the client's IP address.

1

Log in to the MySQL server as a user with administrative privileges (e.g., `root`).

mysql -u root -p

2

Check the host from which the user is allowed to connect. Replace `<username>` and `<host>` with your actual values. Use `%` for any host.

SELECT user, host FROM mysql.user WHERE user = '<username>';

3

If the user is not allowed to connect from the client's host, grant the necessary privileges. Replace `<username>`, `<client_ip_address>`, and `<password>` accordingly.

GRANT ALL PRIVILEGES ON *.* TO '<username>'@'<client_ip_address>' IDENTIFIED BY '<password>';

4

Alternatively, to allow connection from any host (use with caution):

GRANT ALL PRIVILEGES ON *.* TO '<username>'@'%' IDENTIFIED BY '<password>';

5

Apply the privilege changes.

FLUSH PRIVILEGES;

4. Configure Firewall Rules to Allow MySQL Traffic medium

Ensures that network firewalls on both the client and server are not blocking MySQL connections.

1

Identify the firewall software running on the MySQL server (e.g., `ufw`, `firewalld`, `iptables`).

text

2

Add a rule to allow incoming TCP connections on the MySQL port (default 3306) from your client's IP address or subnet.

sudo ufw allow from <client_ip_address> to any port 3306

3

If using `firewalld`:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="<client_ip_address>" port port="3306" protocol="tcp" accept'

4

Reload the firewall rules.

sudo ufw reload

5