How do I troubleshoot the UnknownHostException error in my Java application?

Last updated: 2021-04-26

How do I troubleshoot the UnknownHostException error in my Java application?

Short description

UnknownHostException is a common error message in Java applications. This error typically indicates that there was a DNS resolution failure. However, the message is generic, and it doesn't describe the root cause of the issue. In addition to a DNS issue, the root cause of this error might be:

  • A network outage in an Amazon Elastic Compute Cloud (Amazon EC2) instance
  • A software issue that affected DNS resolution
  • Driver issues

If a Java application fails to get a valid DNS answer, it might throw an UnknownHostException error. Possible causes might include:

  • The application couldn't connect to the configured DNS resolver, so it timed out
  • The application got a NXDOMAIN response
  • The application got a SERVFAIL response, or another type of DNS error
  • The application got a NOERROR response that didn't include a DNS answer


Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

Determine the root cause of the error

Before you can start troubleshooting the UnknownHostException error, you must determine the root cause. To do that, follow these steps:

1.    Use the Windows Remote Desktop Protocol (RDP) or Secure Shell (SSH) protocol to connect to the server that hosts your Java application.

2.    Run a dig command (Linux) or nslookup command (Windows) on the DNS name that caused the error. Then, review the output.

For example, the output should have a NOERROR status, and an Answer section with valid DNS answers:

$ dig

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 9216
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 5

;; ANSWER SECTION:    75347    IN    A

An unexpected output might be similar to the following example. In this case, the output has a SERVFAIL status.

$ dig

;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 57632
;; flags: qr rd ra;

In this example, there's a networking issue at the server or the DNS resolver. The application fails to connect, and then times out.

$ dig

;; global options: +cmd
;; connection timed out; no servers could be reached

Or, you might get a valid NOERROR response. However, if the response is missing a valid Answer section, the result is an UnknownHostException error. This scenario is typically caused when there's a geolocation routing policy, but the record has no a DNS answer for the server's geographic location.

$ dig

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 49948
;; flags: qr rd ra; QUERY: 1,

    300    IN    SOA 1 7200 900 1209600 86400

Troubleshoot application level issues

Application level issues are likely if you get valid answers from the dig or nslookup commands, but continue to receive UnknownHostException errors in your Java application. To resolve application level issues, try the following methods:

  • Restart your application.
  • Confirm that your Java application doesn't have a bad DNS cache. If possible, configure your application to adhere to the DNS TTL. To use a fixed TTL, specify 60 seconds or less. For more information, see Setting the JVM TTL for DNS name lookups.

Check for network outages

If you use an Amazon EC2 instance for your Java application, then network outages are rare but can happen. The dig or nslookup responses will show that you repeatedly can't to connect to the DNS resolver or server. In this case, check for any active network outages in your AWS Region.

If you use an on-premises server that connects to a Route 53 private hosted zone through a Route 53 resolver endpoint, then check the configuration of the endpoint on the VPC. Review settings for the security group, network access control list (network ACL), and route table.

Check your DNS configuration

If you intermittently get the UnknownHostException error, then Amazon EC2 DNS limits might be a factor. The limit is 1,024 packets per second per network interface, and that limit can't be increased. The number of DNS queries per second supported by the Amazon-provided DNS server varies by query type, response size, and protocol type. For more information, see How can I determine whether my DNS queries to the Amazon provided DNS server are failing due to VPC DNS throttling?

If the dig or nslookup command returns an NXDOMAIN or NOERROR (without an answer) response, then check your DNS hosted zone to confirm that the DNS record is correctly configured. If you're using a Route 53 private hosted zone, then confirm that it's associated with the required VPCs.

Did this article help?

Do you need billing or technical support?