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

Last updated: 2022-06-14

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

  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

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 fewer. For more information, see Setting 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 Amazon DNS server.

In following example, DNS support is disabled at the VPC level. The dig query and telnet against VPC resolver (10.1.1.2) is failing, while the dig for cloud-flare DNS server (1.1.1.1) is resolving.

$ 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 scenario is typically caused 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, <b>status: NOERROR</b>, 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

Also, 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, to show NSEC: Note: Replace domain with your domain.

dig <domain> +trace

The output looks similar to:

; <<>> 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 they 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 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. 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, <b>status: SERVFAIL</b>, 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 is replying back with correct answer. If you are using 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) is present in the parent zone but is missing in the child zone, then intermittent NXDOMAIN is expected. Every child zone NS record must be present in its parent hosted zone.

To 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?


Did this article help?


Do you need billing or technical support?