{
  "id": "java/sql-non-transient-connection-exception",
  "signature": "java.sql.SQLNonTransientConnectionException: Could not connect to address=(host=<host>)(port=<port>)(type=master): Connection refused",
  "signature_zh": "java.sql.SQLNonTransientConnectionException：无法连接到地址=(host=<host>)(port=<port>)(type=master)：连接被拒绝",
  "regex": "java\\.sql\\.SQLNonTransientConnectionException.*Could not connect to address=\\(host=.*\\)\\(port=.*\\)\\(type=master\\): Connection refused",
  "domain": "java",
  "category": "network_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "JDBC驱动程序无法建立到指定数据库主机和端口的TCP连接，通常是因为数据库服务器未运行、端口被防火墙阻止或主机名不可达。",
  "versions": [
    {
      "version": "MySQL Connector/J 8.0.33",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PostgreSQL JDBC 42.7.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "HikariCP 5.1.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase connection timeout in JDBC URL (e.g., connectTimeout=60000)",
      "why_fails": "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.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Change the JDBC driver version to an older one",
      "why_fails": "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.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Add useSSL=false to the JDBC URL",
      "why_fails": "SSL configuration is irrelevant when the initial TCP connection cannot be established. The connection refusal happens before any SSL handshake.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.",
      "success_rate": 0.9,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.8,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.85,
      "how": "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.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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.",
    "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.",
    "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."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-usagenotes-connect-driver-manager.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-08-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}