Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

JDBC cannot talk to MySQL: Communications link failure

Errorcom.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

Short answer

Communications link failure means the TCP link to MySQL could not be opened or was closed. If it happens on first connect, the server is down, listening on another port or address, or a firewall blocks it. If it happens after idle time, a timeout or firewall closed the connection.

  • Applies to MySQL 8.4, MySQL Connector/J 9, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Test the same host and port from the machine that runs Java. Forcing TCP with 127.0.0.1 separates socket problems from network problems.

    mysql --host=127.0.0.1 --port=3306 -u root -p -e "SELECT 1"
  2. 2Match what you see, then jump to its fix

    1. 1Fails on the very first connection; root cause is Connection refusedThe server is not running, or the port is differentFix
    2. 2Works on the DB machine, fails from another host or from a containerThe server ignores network connections or a firewall blocks the portFix
    3. 3Works after restart, fails after hours; the message says the last packet was sent a long time agoThe connection sat idle and something closed itFix

What does the error look like?

  • com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure
  • The last packet sent successfully to the server was 0 milliseconds ago.
  • Caused by: java.net.ConnectException: Connection refused

Cause 1 of 3

The server is not running, or the port is different

1Check

Check that mysqld is up and which port it listens on. The client must use the same port as the server.

sudo systemctl status mysql
sudo ss -ltnp | grep mysqld

2Fix

Start the server, or correct the port in the JDBC URL.

sudo systemctl start mysql
# jdbc:mysql://127.0.0.1:3307/app

3Verify

The mysql client from the first step now returns 1.

mysql --host=127.0.0.1 --port=3306 -u root -p -e "SELECT 1"

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 3

The server ignores network connections or a firewall blocks the port

1Check

skip_networking turns TCP off entirely. bind_address = 127.0.0.1 accepts local clients only. Connector/J needs TCP/IP, because named sockets are not supported.

SHOW VARIABLES LIKE 'skip_networking';
SHOW VARIABLES LIKE 'bind_address';

2Fix

Allow the interface your clients use in bind_address, keep skip_networking off, and open the port in the firewall for the Java host only.

# my.cnf
[mysqld]
bind-address = 0.0.0.0
skip_networking = OFF

3Verify

Connect from the Java host with the client command from the first step.

nc -vz db.internal.example 3306

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 3

The connection sat idle and something closed it

1Check

A firewall or router can drop idle connections, and the server closes idle ones after wait_timeout or interactive_timeout.

SHOW VARIABLES LIKE '%timeout';

2Fix

Validate pooled connections with a ping query before use, keep the idle time below the shortest timeout in the path, enable tcpKeepalive, and raise the server timeouts if they are too low. The driver documents the exact ping syntax: it must start with /* ping */.

# JDBC URL
jdbc:mysql://db:3306/app?tcpKeepAlive=true
# pool validation query
/* ping */ SELECT 1

3Verify

Leave the app idle past the old failure time, then call an endpoint that uses the database.

curl -I http://localhost:8080/health

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Use a connection pool that validates connections, not autoReconnect, which the driver docs call deprecated.
  • Retry the transaction when SQLState is 08S01, as the driver docs describe.
  • Keep the app's idle time shorter than the firewall's idle limit.

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

MySQL refuses to delete a row because other rows point to it

SQLIntegrityConstraintViolationException: Cannot delete or update a parent row: a foreign key constraint fails

Error 1451 means at least one child row still references the parent row you are deleting or changing.

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.