JDBC cannot talk to MySQL: Communications link failure
com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failureShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
Fails on the very first connection; root cause is Connection refusedThe server is not running, or the port is differentFix - 2
Works on the DB machine, fails from another host or from a containerThe server ignores network connections or a firewall blocks the portFix - 3
Works after restart, fails after hours; the message says the last packet was sent a long time agoThe connection sat idle and something closed itFix
- 1
What does the error look like?
com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failureThe 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 mysqld2Fix
Start the server, or correct the port in the JDBC URL.
sudo systemctl start mysql
# jdbc:mysql://127.0.0.1:3307/app3Verify
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
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 = OFF3Verify
Connect from the Java host with the client command from the first step.
nc -vz db.internal.example 3306Confirmed by dev.mysql.com
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 13Verify
Leave the app idle past the old failure time, then call an endpoint that uses the database.
curl -I http://localhost:8080/healthConfirmed by dev.mysql.com
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:
- 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
The connection to MySQL dropped while a query was running (error 2013)
ERROR 2006 (HY000): MySQL server has gone away
Error 2013 means the client sent a query or was waiting for the answer and the connection ended.
4 causes, each with a fixDatabases
EntityNotFoundException when loading an entity that has a missing related row
ConstraintViolationException on an orphaned foreign key
EntityNotFoundException means Hibernate followed an id and no row was there.
3 causes, each with a fixDatabases
Hibernate fails on a CREATE or ALTER TABLE statement at startup
Error executing DDL "alter table events drop foreign key FKg0mkvgsqn8584qoql6a2rxheq" via JDBC Statement
Hibernate generated a CREATE, ALTER or DROP statement and MySQL refused it.
3 causes, each with a fixDatabases
MySQL Connector/J: EOFException, expected to read 4 bytes, read 0 bytes
Communications link failure
The MySQL server or something between you and it closed the connection, and the driver found out only when it tried to use it.
3 causes, each with a fixDatabases
Java cannot log in to MySQL 8: authentication plugin caching_sha2_password not supported
ERROR 2061 (HY000): Authentication plugin 'caching_sha2_password' reported error: Authentication requires secure connection.
MySQL 8 accounts use the caching_sha2_password plugin by default, and Connector/J releases before 8.0.9 cannot use it.
3 causes, each with a fixDatabases
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