java network_error ai_generated true

java.sql.SQLNonTransientConnectionException: Could not connect to address=(host=<host>)(port=<port>)(type=master): Connection refused

ID: java/sql-non-transient-connection-exception

Also available as: JSON · Markdown · 中文
85%Fix Rate
85%Confidence
1Evidence
2023-08-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
MySQL Connector/J 8.0.33 active — — —
PostgreSQL JDBC 42.7.1 active — — —
HikariCP 5.1.0 active — — —

Root Cause

The JDBC driver cannot establish a TCP connection to the specified database host and port, typically because the database server is not running, the port is blocked by a firewall, or the hostname is unreachable.

generic

中文

JDBC驱动程序无法建立到指定数据库主机和端口的TCP连接，通常是因为数据库服务器未运行、端口被防火墙阻止或主机名不可达。

Official Documentation

https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-usagenotes-connect-driver-manager.html

Workarounds

  1. 90% success Verify the database server is running and listening on the expected port. On Linux: `sudo netstat -tulpn | grep <port>`. On Windows: `netstat -ano | findstr :<port>`. If not listening, restart the database service. 
    Verify the database server is running and listening on the expected port. On Linux: `sudo netstat -tulpn | grep <port>`. On Windows: `netstat -ano | findstr :<port>`. If not listening, restart the database service.
  2. 80% success Check firewall rules on both host and network level. Temporarily disable the firewall for testing: `sudo ufw disable` (Linux) or `netsh advfirewall set allprofiles state off` (Windows). Re-enable after testing and add an allow rule for the database port. 
    Check firewall rules on both host and network level. Temporarily disable the firewall for testing: `sudo ufw disable` (Linux) or `netsh advfirewall set allprofiles state off` (Windows). Re-enable after testing and add an allow rule for the database port.
  3. 85% success Test connectivity using telnet or nc from the application server: `telnet <host> <port>` or `nc -zv <host> <port>`. If the connection fails, check DNS resolution with `nslookup <host>` and ensure the hostname resolves to the correct IP. 
    Test connectivity using telnet or nc from the application server: `telnet <host> <port>` or `nc -zv <host> <port>`. If the connection fails, check DNS resolution with `nslookup <host>` and ensure the hostname resolves to the correct IP.

中文步骤

  1. Verify the database server is running and listening on the expected port. On Linux: `sudo netstat -tulpn | grep <port>`. On Windows: `netstat -ano | findstr :<port>`. If not listening, restart the database service.
  2. Check firewall rules on both host and network level. Temporarily disable the firewall for testing: `sudo ufw disable` (Linux) or `netsh advfirewall set allprofiles state off` (Windows). Re-enable after testing and add an allow rule for the database port.
  3. Test connectivity using telnet or nc from the application server: `telnet <host> <port>` or `nc -zv <host> <port>`. If the connection fails, check DNS resolution with `nslookup <host>` and ensure the hostname resolves to the correct IP.

Dead Ends

Common approaches that don't work:

  1. Increase connection timeout in JDBC URL (e.g., connectTimeout=60000) 95% fail

    Timeout only affects how long the driver waits for a response; if the server is down or port is closed, timeout does not help. The connection will still fail after the extended timeout.

  2. Change the JDBC driver version to an older one 90% fail

    The error is a network-level issue, not a driver compatibility problem. Changing the driver version does not affect TCP connectivity to the database server.

  3. Add useSSL=false to the JDBC URL 85% fail

    SSL configuration is irrelevant when the initial TCP connection cannot be established. The connection refusal happens before any SSL handshake.