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

Short description

UnknownHostException is a common error message in Java applications. This error is usually caused by a DNS resolution failure. If a Java application fails to get a valid DNS answer, then it might throw an UnknownHostException error.

In addition to a DNS issue, the root cause of this error might be:

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

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Determine the root cause of the error

Complete the following 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.
3. Based on the output, review the following scenarios.

Valid answers from dig or nslookup commands

You might get valid answers from the dig or nslookup commands, but receive UnknownHostException errors in your Java application. This is likely because of application level issues.

To resolve application level issues, do the following:

• Restart your application.
• Confirm that your Java application doesn't have a bad DNS cache. Configure your application to adhere to the DNS time-to-live (TTL). To use a fixed TTL, specify 60 seconds or less. For more information, see Set the JVM TTL for DNS name lookups.

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

$ dig timeout.example.com
;; global options: +cmd
;; connection timed out; no servers could be reached

If the dig command from Amazon EC2 instances show no servers could be reached, then verify if the DNS support option is turned on for the source VPC. For more information, see DNS attributes for your VPC.

In following example, DNS support is turned off at the VPC level. The first dig command that is used to query the VPC resolver (10.1.1.2) fails, as does the Telnet connection to the VPC Resolver (10.1.1.2). However, the second dig command used to query the Cloudflare DNS server (1.1.1.1) resolves to an answer.

$ dig google.com; <<>> DiG 9.11.4-P2-RedHat-9.11.4-26.P2.amzn2.5.2 <<>> google.com
;; global options: +cmd
;; connection timed out; no servers could be reached

$ telnet 10.1.1.2 53
Trying 10.1.1.2...
telnet:connect to address 10.1.1.2: No route to host

$ dig google.com @1.1.1.1 +short
142.251.16.102
142.251.16.139
142.251.16.138
142.251.16.113
142.251.16.101
142.251.16.100

Valid NOERROR response with missing valid Answer section

This error commonly occurs when there's a geolocation routing policy, but the record doesn't have a DNS answer for the server's geographic location. You can either create a record and define the geolocation records, or create a default record.

The following is an example output of this scenario:

$ dig noanswer.example.com
;; ->>HEADER<<- opcode: QUERY, **status: NOERROR**, id: 49948
;; flags: qr rd ra; QUERY: 1,
    ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1

;; AUTHORITY SECTION:
example.com.   
    300    IN    SOA    ns1.example.com. ns2.example.com. 1 7200 900 1209600 86400

If the DNS record isn't created in a public hosted zone and Domain Name System Security Extensions (DNSSEC) is turned on, then NOERROR - NOANSWER is returned instead of NXDOMAIN.

To verify the status of DNSSEC, run the following dig command.

Note: Replace domain with your domain.

dig  +trace

The output looks similar to the following example:

; <<>> DiG 9.11.4-P2-RedHat-9.11.4-26.P2.amzn2.5.2 <<>> example.co.uk;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 43917
;; flags: qr rd ra; QUERY: 1, ANSWER:0, AUTHORITY: 1, ADDITIONAL: 1
;; AUTHORITY SECTION:
example.co.uk. 300 IN SOA ns-1578.awsdns-05.co.uk. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400

In the following example, the dig output shows NXDOMAIN for DNS records that aren't created and DNSSEC isn't turned on:

$ dig example.amazon.com; <<>> DiG 9.11.4-P2-RedHat-9.11.4-26.P2.amzn2.5.2 <<>>
    example.amazon.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 64351
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1
;; AUTHORITY SECTION:
amazon.com. 24 IN SOA dns-external-master.amazon.com. root.amazon.com. 2010158906 180 60 3024000 60

NXDOMAIN or NOERROR (without an answer) response

Check your DNS public hosted zone to confirm that the DNS record is correctly configured.

SERVFAIL status
-or-
Can't connect to the DNS resolver or server

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

If all of the following are true, then check the configuration of the endpoint on the VPC:

• You use an on-premises server.
• The on-premise server connects to a Route 53 private hosted zone through a Route 53 resolver endpoint.

Review settings for the security group, network access control list (network ACL), and route table. For instructions, see How do I troubleshoot Amazon EC2 instance connection timeout errors from the internet?

In this example, the output has a SERVFAIL status:

$ dig servfail.example.com
;; ->>HEADER<<- opcode: QUERY, **status: SERVFAIL**, id: 57632
;; flags: qr rd ra;
    QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1

Check if private hosted zone and resolver rule are associated to source VPC

The Amazon-provided DNS resolver evaluates the most specific match, in the following priority order:

1. Resolver rule
2. Private hosted zone
3. Public hosted zone

If DNS query matches the resolver rule, then confirm that the target IP address replies back with the correct answer. If you use a private hosted zone, then be sure that the DNS record is created in your private hosted zone. If DNS record isn't present in private hosted zone, then it doesn't fallback to a public hosted zone and returns NXDOMAIN.

For more information, see Resolving DNS queries between VPCs and your network.

Check for subdomain delegation issues

Verify the proper sub-domain delegation is created between parent, child, and grandchild zone. If grandchild zone name servers (NS) are present in the parent zone but not present in the child zone, then intermittent NXDOMAIN is expected. Every child zone NS record must be present in its parent hosted zone.

Avoid intermittent DNS resolution issues

The following is an example of domain delegation:

• Parent zone: example.com
• Child zone: today.example.com
• Grandchild zone: api.today.example.com

When the grandchild zone (api.today.example.com) NS record is present in parent zone (example.com), then be sure it's also present in child zone (today.example.com). For more information, see How do I test if my delegated subdomain resolves correctly?

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?