How do I troubleshoot Amazon SQS “ETIMEOUT” and “UnknownHostException” connection errors?

Short description

I received an "ETIMEOUT" or "UnknownHostException" connection error with Amazon Simple Queue Service (Amazon SQS).

Resolution

To troubleshoot, follow these steps for your use case.

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

Troubleshoot "ETIMEOUT" errors

The "ETIMEOUT" error occurs when the client can't establish a TCP connection to an Amazon SQS endpoint.

Check the network connection

Run the telnet command to test your Amazon SQS network connection.Windows and Linux OS:

telnet <region>.queue.amazonaws.com 443

Note: Replace the endpoint with your endpoint.

Example successful connection:

telnet queue.amazonaws.com 443
Trying 3.239.232.91...
Connected to queue.amazonaws.com.
Escape character is '^]'.

Example unsuccessful connection:

telnet queue.amazonaws.com 443
Trying 3.239.232.91...
telnet: connect to address 3.239.232.91: Connection timed out

Check network settings

• Make sure that your local firewall rules, routes, and access control lists (ACLs) allow traffic on the port that you use.
• The security group outbound (egress) rules must allow traffic to the port 80 or 443.
• The network ACL outbound (egress) rules must allow traffic to TCP port 80 or 443.
• The network ACL inbound (ingress) rules must allow traffic on TCP ports 1024-65535.
• Amazon Elastic Compute Cloud (Amazon EC2) instances that connect to the public internet must have internet connectivity.

Amazon Virtual Private Cloud (Amazon VPC) endpoints

If you access SQS through an Amazon VPC, then the endpoints security group must allow inbound traffic to the clients security group on port 443. The network ACL associated with the subnet of the VPC endpoint must have this configuration:

• The network ACL outbound (egress) rules must allow traffic on TCP ports 1024-65535 (ephemeral ports).
• The network ACL inbound (ingress) rules must allow traffic on port 443.

Also, the SQS VPC endpoint AWS Identity and Access Management (IAM) policy must allow access.

This example VPC endpoint policy specifies that the IAM user MyUser is allowed to send messages to the SQS queue MyQueue. Other actions, IAM users, and SQS resources are denied access through the VPC endpoint.

{
   "Statement": [{
      "Action": ["sqs:SendMessage"],
      "Effect": "Allow",
      "Resource": "arn:aws:sqs:us-east-2:123456789012:MyQueue",
      "Principal": {
        "AWS": "arn:aws:iam:123456789012:user/MyUser"
      }
   }]
}

Troubleshoot "UnknownHostException" errors

The "UnknownHostException" error occurs when the host IP address couldn't be determined.

Use the nslookup utility to return the IP address associated with the host name:

Windows and Linux OS:

nslookup sqs.<region>.amazonaws.com 

AWS CLI or SDK for Python legacy endpoints:

nslookup <region>.queue.amazonaws.com

Example successful output:

nslookup queue.amazonaws.com
Server: 10.4.4.10
Address: 10.4.4.10#53

Non-authoritative answer:
Name: queue.amazonaws.com
Address: 3.239.232.201

The preceding example indicates that the domain name resolved correctly on the DNS server.

If you received an unsuccessful output, follow the instructions in How does DNS work and how do I troubleshoot partial or intermittent DNS failures?

Related information

What permissions do I need to access an Amazon SQS queue?

How do I troubleshoot "AccessDenied" or "AccessDeniedException" errors on Amazon SQS API calls?