How do I troubleshoot the Amazon S3 errors that I receive from AWS SDK for Java exceptions?

Short description

When you use AWS SDKs, you might receive the following client and service errors:

• AmazonClientException or SdkClientException
• AmazonServiceException, AwsServiceException, or AmazonS3Exception
• UnknownHostException

To troubleshoot the preceding errors, first identify the exception type, and then complete the resolution for your issue.

Resolution

AmazonClientException or SdkClientException

AmazonClientException or SdkClientException occurs when you can't send a request to or parse a response from AWS because of errors in the client code.

To resolve the issue, take the following actions:

• Check your local environment's use of proxy settings, and set the proxy configuration in your code's S3Client. If you're using AWS SDK for Java 2.x, then configure your S3 client to use HTTP proxies.
  If you're using the AWS SDK for Java 1.x, then use the following code to update your S3 client configuration:

  // Proxy configuration Java 1.x
          ClientConfiguration clientConfig = new ClientConfiguration();
          clientConfig.setProxyHost("your_proxy.example.com");
          clientConfig.setProxyPort(YOUR_PROXY_PORT);
          
          // Optional: If proxy requires authentication
          clientConfig.setProxyUsername(YOUR_PROXY_USERNAME);
          clientConfig.setProxyPassword(YOUR_PROXY_PASSWORD);
  
          // Create S3 client with proxy configuration
          AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                  .withRegion(YOUR_REGION)
                  .withCredentials(new AWSStaticCredentialsProvider(credentials))
                  .withClientConfiguration(clientConfig)
                  .build(); 

• Test your network connectivity to S3 endpoints with tools such as nslookup, ping, cURL or telnet. To troubleshoot network connectivity issues, see How do I troubleshoot a connection error when I run the "cp" or "sync" commands on my Amazon S3 bucket?

• Print or log your S3 client configurations to check that you that you correctly configured your S3 client.
  Example configuration:

  // AWS SDK for Java v1.x
      
      public static void validateClientConfiguration(AmazonS3 s3Client) {
          try {
              // See: https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.html
              ClientConfiguration config = s3Client.getClientConfiguration();
  
              System.out.println("=== Currnt S3 Client Configuration ===");
  
              // Connection Settings
              System.out.println("Max Connections: " + config.getMaxConnections());
              System.out.println("Connection Timeout: " + config.getConnectionTimeout() + "ms");
              System.out.println("Socket Timeout: " + config.getSocketTimeout() + "ms");
              System.out.println("Request Timeout: " + config.getRequestTimeout() + "ms");
              System.out.println("Client Execution Timeout: " + config.getClientExecutionTimeout() + "ms");
  
              // Retry Settings
              System.out.println("Max Error Retry: " + config.getMaxErrorRetry());
              System.out.println("Retry Policy: " + config.getRetryPolicy());
  
              // Proxy Settings
              if (config.getProxyHost() != null) {
                  System.out.println("Proxy Host: " + config.getProxyHost());
                  System.out.println("Proxy Port: " + config.getProxyPort());
              }
  
              // Protocol Settings
              System.out.println("Protocol: " + config.getProtocol());
             
              // Region/Endpoint but only if you are using the AmazonS3ClientBuilder client
              // See https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3ClientBuilder.html
              
              System.out.println("Region: " + s3Client.getRegion());
  
            
          } catch (Exception e) {
              System.err.println("Error validating client configuration: " + e.getMessage());
          }
      }

• Check whether there are connection or resource constraints in the HTTP Transport settings in your S3 client configuration. For more information see, Client configuration and HTTP clients. 

• Run the following try-catch-finally command to close your S3 client as soon as possible so that other requests can use the connection:

  try {
              .... // your code
          } catch (Exception e) {
              .... // catch exception
          } finally {
              // close the S3 client
              s3Client.close();
          }

• If you're using temporary credentials, then run the following try-catch command to confirm that your credentials didn't expire:

  // sample method for AWS SDK Java 2.x 
      public static boolean areCredentialsExpired(AwsCredentialsProvider credentialsProvider) {
          try {
              AwsCredentials credentials = credentialsProvider.resolveCredentials();
              
              if (credentials instanceof AwsSessionCredentials) {
                  return false;
              }
          } catch (S3Exception e) {
              //Check if exception contains any expired credentials indication.
              if("ExpiredToken".equals(e.awsErrorDetails().errorCode())){
                 return true; 
              }
          } catch (Exception e) {
              // If we can't resolve credentials, they're likely expired
              return true;
          }
          
          return true;
      }

AmazonServiceException, AwsServiceException, or AmazonS3Exception

If you receive an AmazonServiceException, AwsServiceException, or AmazonS3Exception error, then an issue occurred after you successfully sent the request to the AWS service. To resolve the issue, check the HTTP status code in the stack trace response. The following examples are some of the status code errors that you might encounter. For a full list of HTTP status codes, see List of error codes.

HTTP 400

The HTTP 400 error occurs because of incorrect request syntax. Before you send your request to Amazon S3, temporarily log or print your request to check your request syntax.

HTTP 409

Check whether Amazon S3 removed a recently deleted bucket before you create new one.

HTTP 403

You receive an Access denied error when you don't have permission to perform actions. Check your AWS Identity and Access Management (IAM) permissions, service control policies (SCPs), S3 bucket policy, and object ownership to make sure that you have sufficient permissions. Also, make sure that your credentials didn't expire.

The Access denied error also occurs when an IAM principal requests an object without "s3:ListBucket" permissions and the object doesn't exist in the S3 bucket.

For more information, see Troubleshoot access denied (403 Forbidden) errors in Amazon S3.

HTTP 404

Make sure that the S3 object exists in the bucket.

HTTP 500

Retry your requests, or introduce a delay in your code. By default, each AWS SDK standard retry mode has three maximum attempts. If these attempts don't resolve your issue, then increase the value.

HTTP 503

Distribute your objects across multiple prefixes. For more information, see How do I troubleshoot a HTTP 500 or 503 error from Amazon S3?

UnknownHostException

If you receive an UnknownHostException error, then make sure that there are no DNS resolution issues toward the S3 endpoints.

Related information

Exception handling for the AWS SDK for Java 2.x.x

Exception handling