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

- **ID:** `java/sql-non-transient-connection-exception`
- **Domain:** java
- **Category:** network_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| MySQL Connector/J 8.0.33 | active | — | — |
| PostgreSQL JDBC 42.7.1 | active | — | — |
| HikariCP 5.1.0 | active | — | — |

## Workarounds

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.** (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.
   ```
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.** (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.
   ```
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.** (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.
   ```

## Dead Ends

- **Increase connection timeout in JDBC URL (e.g., connectTimeout=60000)** — 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. (95% fail)
- **Change the JDBC driver version to an older one** — 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. (90% fail)
- **Add useSSL=false to the JDBC URL** — SSL configuration is irrelevant when the initial TCP connection cannot be established. The connection refusal happens before any SSL handshake. (85% fail)