문제 해결 FAQ

애플리케이션에서 AWS SDK for Java 2.x를 사용할 때 이 주제에 나열된 런타임 오류가 발생할 수 있습니다. 여기에서 제안 사항을 사용하면 근본 원인을 파악하고 오류를 해결하는 데 도움이 됩니다.

‘java.net.SocketException: 연결 재설정’ 또는 ‘서버가 응답을 완료하지 못함’ 오류 해결 방법

연결 재설정 오류는 호스트, AWS 서비스 또는 중개자(예: NAT 게이트웨이, 프록시, 로드 밸런서)가 요청이 완료되기 전에 연결을 종료했음을 나타냅니다. 원인에는 여러 가지가 있으므로 솔루션을 찾으려면 연결이 종료되는 이유를 알아야 합니다. 다음 항목으로 인해 일반적으로 연결이 종료됩니다.

문제를 파악할 수 없는 경우 네트워크의 클라이언트 엣지에서 영향을 받는 연결에 대해 TCP 덤프를 실행합니다(예: 제어하는 프록시 이후).

AWS 엔드포인트가 TCP RST를 전송(재설정)하는 경우 영향을 받는 서비스에 문의하여 재설정이 발생하는 이유를 확인할 수 있는지 알아봅니다. 문제가 발생한 때의 요청 ID와 타임스탬프를 제공할 준비를 합니다. 또한 AWS 지원 팀은 애플리케이션이 전송 및 수신하는 바이트와 시기를 정확하게 보여주는 유선 로그의 이점을 누릴 수 있습니다.

‘연결 제한 시간’을 수정하는 방법

연결 제한 시간 오류는 호스트, AWS 서비스 또는 중개자(예: NAT 게이트웨이, 프록시, 로드 밸런서)가 구성된 연결 제한 시간 내에 서버와 새 연결을 설정하지 못했음을 나타냅니다. 다음 항목에서는 이 문제의 일반적인 원인을 설명합니다.

문제를 파악할 수 없는 경우 네트워크의 클라이언트 엣지에서 영향을 받는 연결에 대해 TCP 덤프를 실행하여(예: 제어하는 프록시 이후) 네트워크 문제를 조사합니다.

‘java.net.SocketTimeoutException: 읽기 제한 시간’을 수정하는 방법

읽기 제한 시간 오류는 JVM이 기본 운영 체제에서 데이터를 읽으려고 시도했지만 SDK를 통해 구성된 시간 내에 데이터가 반환되지 않았음을 나타냅니다. 이 오류는 운영 체제, AWS 서비스 또는 중개자(예: NAT 게이트웨이, 프록시, 로드 밸런서)가 JVM에서 예상한 시간 내에 데이터를 전송하지 못하는 경우에 발생할 수 있습니다. 원인에는 여러 가지가 있으므로 솔루션을 찾으려면 데이터가 반환되지 않는 이유를 알아야 합니다.

네트워크의 클라이언트 엣지에서 영향을 받는 연결에 대해 TCP 덤프를 실행해 봅니다(예: 제어하는 프록시 이후).

AWS 엔드포인트가 TCP RST(재설정)를 전송하고 있는 경우 영향을 받는 서비스에 문의하세요. 문제가 발생한 때의 요청 ID와 타임스탬프를 제공할 준비를 합니다. 또한 AWS 지원 팀은 애플리케이션이 전송 및 수신하는 바이트와 시기를 정확하게 보여주는 유선 로그의 이점을 누릴 수 있습니다.

‘HTTP 요청을 실행할 수 없음: 풀에서 연결을 기다리는 제한 시간’ 오류를 해결하는 방법

이 오류는 요청이 지정된 최대 시간 내에 풀에서 연결을 가져올 수 없음을 나타냅니다. 문제를 해결하려면 SDK 클라이언트 측 지표를 사용하여 Amazon CloudWatch에 지표를 게시하는 것이 좋습니다. HTTP 지표는 근본 원인의 범위를 좁히는 데 도움이 될 수 있습니다. 다음 항목에서는 이 오류의 일반적인 원인을 설명합니다.

NoClassDefFoundError, NoSuchMethodError 또는 NoSuchFieldError를 수정하는 방법

NoClassDefFoundError는 런타임에 클래스를 로드할 수 없음을 나타냅니다. 이 오류의 가장 일반적인 2가지 원인은 다음과 같습니다.

마찬가지로 NoSuchMethodError 및 NoSuchFieldError는 일반적으로 JAR 버전이 일치하지 않아 발생합니다. 다음 단계를 수행하는 것을 권장합니다.

‘SignatureDoesNotMatch’ 오류 또는 ‘계산한 요청 서명이 제공한 서명과 일치하지 않음’ 오류를 해결하는 방법

SignatureDoesNotMatch 오류는 AWS SDK for Java에서 생성된 서명과 AWS 서비스에서 생성된 서명이 일치하지 않음을 나타냅니다. 다음 항목에서는 잠재적 원인을 설명합니다.

이 문제를 디버깅하려면 SDK에 대한 디버그 로깅을 사용하는 것이 좋습니다. 오류를 재현하고 SDK가 생성한 정식 요청을 찾습니다. 로그에서 정식 요청에는 레이블이 AWS4 String to sign: ...으로 지정되고 서명할 문자열에는 AWS4 Canonical Request: ... 레이블이 지정됩니다.

예를 들어 프로덕션 환경에서만 재현할 수 있기 때문에 디버깅을 사용할 수 없는 경우 오류가 발생하면 요청에 대한 정보를 로깅하는 로직을 애플리케이션에 추가합니다. 그런 다음 해당 정보를 사용하여 디버그 로깅이 사용된 통합 테스트 시 프로덕션 외부에서 오류를 복제할 수 있습니다.

서명할 정식 요청과 문자열을 수집한 후 AWS 서명 버전 4 사양과 비교하여 SDK가 서명할 문자열을 생성한 방식에 문제가 있는지 확인합니다. 문제가 있는 것 같으면 AWS SDK for Java에 대한 GitHub 버그 보고서를 만들 수 있습니다.

문제가 전혀 표시되지 않으면 서명할 SDK의 문자열을 문자열과 비교하여 일부 AWS 서비스가 실패 응답의 일부로 반환된다고 서명할 수 있습니다(예: Amazon S3). 사용할 수 없는 경우 영향을 받는 서비스에 문의하여 비교를 위해 생성한 정식 요청과 문자열을 확인해야 합니다. 이러한 비교는 서비스와 클라이언트 간의 요청 또는 인코딩 차이를 수정했을 수 있는 중개자를 식별하는 데 도움이 될 수 있습니다.

요청 서명에 대한 자세한 배경 정보는 AWS Identity and Access Management 사용 설명서의 AWS API 요청에 서명을 참조하세요.

PUT
/Example-Bucket/Example-Object
partNumber=19&uploadId=string
amz-sdk-invocation-id:f8c2799d-367c-f024-e8fa-6ad6d0a1afb9
amz-sdk-request:attempt=1; max=4
content-encoding:aws-chunked
content-length:51
content-type:application/octet-stream
host:xxxxx
x-amz-content-sha256:STREAMING-UNSIGNED-PAYLOAD-TRAILER
x-amz-date:20240308T034733Z
x-amz-decoded-content-length:10
x-amz-sdk-checksum-algorithm:CRC32
x-amz-trailer:x-amz-checksum-crc32

AWS4-HMAC-SHA256
20240308T034435Z
20240308/us-east-1/s3/aws4_request
5f20a7604b1ef65dd89c333fd66736fdef9578d11a4f5d22d289597c387dc713

‘java.lang.IllegalStateException: 연결 풀 종료’ 오류를 해결하는 방법

이 오류는 기본 Apache HTTP 연결 풀이 종료되었음을 나타냅니다. 다음 항목에서는 잠재적 원인을 설명합니다.

‘AwsCredentialsProviderChain 체인의 공급자로부터 자격 증명을 로드할 수 없음’ 오류를 수정하는 방법

이 오류는 AWS SDK for Java 2.x가 기본 자격 증명 공급자 체인의 자격 증명 공급자를 통해 유효한 AWS 자격 증명을 찾을 수 없음을 나타냅니다. SDK는 특정 순서로 자격 증명을 자동으로 검색하며, 이 오류는 체인의 모든 공급자가 유효한 자격 증명을 제공하지 못할 때 발생합니다.

전체 오류 메시지는 일반적으로 다음과 같습니다(가독성을 높이기 위해 줄 끝 및 들여쓰기가 추가됨).

Unable to load credentials from any of the providers in the chain AwsCredentialsProviderChain(
    credentialsProviders=[
        SystemPropertyCredentialsProvider(),
        EnvironmentVariableCredentialsProvider(), 
        WebIdentityTokenCredentialsProvider(), 
        ProfileCredentialsProvider(profileName=default, profileFile=ProfileFile(sections=[])), 
        ContainerCredentialsProvider(), 
        InstanceProfileCredentialsProvider()
    ]) : [
        SystemPropertyCredentialsProvider(): Unable to load credentials from system settings.
        Access key must be specified either via environment variable (AWS_ACCESS_KEY_ID) 
        or system property (aws.accessKeyId)., 

        EnvironmentVariableCredentialsProvider(): Unable to load credentials from system settings. 
        Access key must be specified either via environment variable (AWS_ACCESS_KEY_ID) 
        or system property (aws.accessKeyId)., 

        WebIdentityTokenCredentialsProvider(): To use web identity tokens, the 'sts' service module 
        must be on the class path., 

        ProfileCredentialsProvider(profileName=default, profileFile=ProfileFile(sections=[])): 
        Profile file contained no credentials for profile 'default': ProfileFile(sections=[]), 

        ContainerCredentialsProvider(): Cannot fetch credentials from container - neither 
        AWS_CONTAINER_CREDENTIALS_FULL_URI or AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment 
        variables are set., 

        InstanceProfileCredentialsProvider(): Failed to load credentials from IMDS.]

일반적인 원인 및 솔루션

자격 증명 구성 검토

기본 자격 증명 공급자를 사용하는 경우(자격 증명을 명시적으로 구성하지 않고 ServiceClient.create() 호출) SDK는 특정 순서로 자격 증명을 검색합니다. 기본 자격 증명 공급자 체인이 작동하는 방식을 검토하여 SDK가 확인하는 자격 증명과 순서를 파악합니다.

사용하려는 자격 증명 구성 메서드가 환경에 올바르게 설정되어 있는지 확인합니다.

Amazon EC2 인스턴스의 경우

컨테이너 환경의 경우

작업 역할(Amazon ECS) 또는 서비스 계정(Amazon EKS)이 구성되어 있고 필요한 환경 변수가 설정되어 있는지 확인합니다.

로컬 개발의 경우

환경 변수, 자격 증명 파일 또는 IAM Identity Center 구성이 있는지 확인합니다.

웹 ID 페더레이션의 경우

네트워크 또는 프록시 연결 문제

자격 증명 공급자 체인에 Connection refused 오류가 표시되는 경우 이는 일반적으로 SDK가 AWS 엔드포인트에 도달하려고 할 때의 네트워크 연결 문제를 나타냅니다.

솔루션