How do I troubleshoot a connection error when I run the “cp” or “sync” commands on my Amazon S3 bucket?

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

To run the cp or sync commands on the AWS CLI, your machine must connect to the correct Amazon S3 endpoints. Otherwise, you get an error with a message that the service can't connect to the endpoint URL, or that the connection timed out. Take the following troubleshooting actions based on the error that you receive.

"Could not connect to the endpoint URL" error

Confirm that you have the correct Region and Amazon S3 endpoint

When you run a command in the AWS CLI, it sends API requests to the default Amazon S3 endpoint for the AWS Region. When you specify a Region, the AWS CLI sends an API request to a Region-specific Amazon S3 endpoint. Then, the AWS CLI redirects the request to the bucket's Regional Amazon S3 endpoint.

You might get the "Could not connect to the endpoint URL" error if there's a typo or error in the specified Region or endpoint. For example, the following command returns the error because there's an extra e in the endpoint name:

aws s3 cp filename s3://amzn-s3-demo-bucket/ --endpoint-url https://s3-acceleratee.amazonaws.com

Before you run the cp or sync command, confirm that the associated Region and Amazon S3 endpoint are correct. Use the --debug flag when you run the AWS CLI command to identify the endpoint that the AWS CLI uses. Example command:

aws s3 cp filename s3://amzn-s3-demo-bucket/ --debug

Note: If you use Amazon S3 Transfer Acceleration, then turn it on for the bucket. Use the endpoint bucket-name.s3-accelerate.amazonaws.com. Or, use the dual-stack endpoint bucket-name.s3-accelerate.dualstack.amazonaws.com to connect to the bucket over IPv6. Replace bucket-name with your bucket name.

Verify that your DNS can resolve to the Amazon S3 endpoints

To confirm that your DNS can resolve to the Amazon S3 endpoints, use a DNS query tool, such as nslookup, dig or ping. Example commands:

nslookup s3.amazonaws.com

dig s3.amazonaws.com

ping s3.amazonaws.com

If your DNS can't resolve to the Amazon S3 endpoints, then troubleshoot your DNS configuration. If you use Amazon Route 53 as your DNS provider, then see Troubleshooting Amazon Route 53.

"Connect timeout on endpoint URL" error

Verify that your network can connect to the Amazon S3 endpoints

Confirm that your network's firewall allows traffic to the Amazon S3 endpoints on the port that you use for Amazon S3 traffic.

For example, the following telnet command tests the connection to the ap-southeast-2 Amazon S3 endpoint on port 443:

telnet s3.ap-southeast-2.amazonaws.com 443

To capture and analyze network packets and verify that your machine can successfully complete the TCP handshake with the Amazon S3 endpoint, run the following tcpdump command:

sudo tcpdump -i eth0 'host s3.ap-southeast-2.amazonaws.com and port 443' -s0 -w samplecapture.pcap

Note: Replace eth0 with your elastic network interface, ap-southeast-2 with your Amazon S3 endpoint Region and 443 with your port. The -s0 flag captures the full packet and -w samplecapture.pcap writes the capture to a file. You can use a tool such as Wireshark to analyze the information in the file.

Look for the TCP three-way handshake (SYN, SYN-ACK, ACK) to confirm connectivity. If you see only SYN packets without SYN-ACK responses, then there's a firewall or routing issue.

To detect routing issues or packet loss along the path to the Amazon S3 endpoint, run the following mtr command:

mtr -n -T -c 200 s3.ap-southeast-2.amazonaws.com -P 443 --report

Note: Replace ap-southeast-2 with your Region and 443 with your port. The -n flag deactivates DNS resolution to speed up the test and the -T flag uses TCP packets that can be more accurate than Internet Control Messenger Protocol (ICMP). The preceding command runs 200 cycles of the test for better statistical accuracy and generates a report.

On Windows, you can use WinMTR for similar routing tests. Look for high latency, dropped packets, or routing loops that might affect connectivity to the Amazon S3 endpoint.

For an Amazon EC2 instance, check the VPC configuration

If you see the "Connection timeout" error on an Amazon Elastic Compute Cloud (Amazon EC2) instance, then check your virtual private cloud (VPC) configuration.

If the EC2 instance is in a public subnet, then check the following settings:

• Confirm that you set the outbound rule for port 443 to ALLOW in the network access control list (network ACL) of the instance's VPC.
• If the network ACL restricts access to a specific Region of Amazon S3 IP address ranges, then check the AWS CLI configuration file. Confirm that you specify the correct Region.

If the EC2 instance is in a private subnet, then check the following settings:

• Make sure that you associated a NAT gateway with the subnet's route table of the subnet.
• If you use a VPC endpoint for Amazon S3, then confirm that the AWS CLI configuration file has the correct Region.
  Note: VPC endpoints for Amazon S3 are Region specific. For example, you run sync with --region us-west-1 but the VPC endpoint is in a different Region. As a result, you receive the "Could not connect to the endpoint URL" error.

When you use AWS PrivateLink to access Amazon S3 within your VPC, use the Reachability Analyzer. This tool helps you identify misconfigurations in security groups, network ACLs, or route tables that might block connectivity. For example, create a Reachability Analyzer analysis to check the path between your instance and the interface endpoint.