기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 문제 해결 FAQ
애플리케이션에서 AWS SDK for Kotlin 를 사용할 때이 주제에 나열된 몇 가지 문제가 발생할 수 있습니다. 다음 제안을 사용하면 근본 원인을 파악하고 오류를 해결하는 데 도움이 됩니다.
## "연결 닫힘" 문제를 해결하려면 어떻게 해야 합니까?
다음 유형 중 하나와 같은 예외로 '연결 닫힘' 문제가 발생할 수 있습니다.
+ `IOException: unexpected end of stream on `
+ `EOFException: \n not found: limit=0`
+ `HttpException: AWS_ERROR_HTTP_CONNECTION_CLOSED: The connection has closed or is closing.; crtErrorCode=2058; HttpErrorCode(CONNECTION_CLOSED)`
이러한 예외는 SDK에서 서비스로의 TCP 연결이 예기치 않게 닫히거나 재설정되었음을 나타냅니다. 호스트, AWS 서비스 또는 NAT 게이트웨이, 프록시 또는 로드 밸런서와 같은 중개자가 연결을 종료했을 수 있습니다.
이러한 유형의 예외는 자동으로 재시도되지만 로깅 구성에 따라 SDK 로그에 계속 표시될 수 있습니다. 코드에 예외가 발생하면 활성 재시도 전략이 최대 시도 횟수 또는 재시도 토큰 버킷과 같이 구성된 제한을 소진했음을 나타냅니다. 재시도 전략에 대한 자세한 내용은이 가이드의 [에서 재시도 AWS SDK for Kotlin](retries.md) 섹션을 참조하세요. 또한 [최대 시도 횟수에 도달하기 전에 예외가 발생하는 이유는 무엇입니까?](#ts-faq-exceptions-before-max) 섹션도 참조하세요.
### OkHttpEngine을 사용한 유휴 연결 모니터링
를 사용 중`OkHttpEngine`이고 `IOException: unexpected end of stream on ` 예외가 자주 발생하는 경우 [유휴 연결 모니터링을 활성화하는 것이 좋습니다](http-client-config.md#http-idle-connection-monitoring). 이 기능은 원격 서버에 아직 연결 풀에 있는 연결이 닫힌 경우를 감지하여 이러한 예외의 발생을 줄일 수 있습니다.
## 최대 시도 횟수에 도달하기 전에 예외가 발생하는 이유는 무엇입니까?
경우에 따라 재시도할 것으로 예상되었지만 대신 발생했던 예외가 표시될 수 있습니다. 이러한 상황에서는 다음 단계가 문제를 해결하는 데 도움이 될 수 있습니다.
+ **예외를 재시도할 수 있는지 확인합니다.** 예를 들어 잘못된 서비스 요청, 권한 부족 및 존재하지 않는 리소스를 나타내는 예외와 같은 일부 예외는 재시도할 수 없습니다. SDK는 이러한 종류의 예외를 자동으로 재시도하지 않습니다. 재시도 가능한 예외를 확인하는 방법에 대한 자세한 내용은 섹션을 참조하세요[예외를 재시도할 수 있는지 확인](retries.md#retries-check-exception-retryable).
+ **예외가 코드에 발생하고 있는지 확인합니다.** 일부 예외는 로그 메시지에 정보로 표시되지만 실제로 코드에 발생하지는 않습니다. 예를 들어 SDK가 여러 backoff-and-retry 가능한 예외가 로깅될 수 있습니다. SDK 작업을 호출하면 구성된 재시도 설정에서 처리하지 않은 경우에만 예외가 발생합니다.
+ **구성된 재시도 설정을 확인합니다.** 재시도 전략 및 재시도 정책에 대한 자세한 내용은이 가이드의 [에서 재시도 AWS SDK for Kotlin](retries.md) 섹션을 참조하세요. 코드가 예상한 설정 또는 자동 기본값을 사용하고 있는지 확인합니다.
+ **재시도 설정을 조정하는 것이 좋습니다.** 이전 항목을 확인했지만 문제가 해결되지 않은 경우 재시도 설정 조정을 고려할 수 있습니다.
+ **최대 시도 횟수를 늘립니다.** 기본적으로 작업에 대한 최대 시도 횟수는 3회입니다. 이것이 충분하지 않고 기본 설정에서 여전히 예외가 발생하는 경우 클라이언트 구성에서 `retryStrategy.maxAttempts` 속성을 늘리는 것이 좋습니다. 자세한 정보는 [최대 시도 횟수 구성](retries.md#retires-max-attempts)을 참조하세요.
+ **지연 설정을 늘립니다.** 일부 예외는 기본 조건이 해결될 가능성이 있기 전에 너무 빨리 재시도될 수 있습니다. 이 경우 클라이언트 구성에서 `retryStrategy.delayProvider.initialDelay` 또는 `retryStrategy.delayProvider.maxBackoff` 속성을 늘리는 것이 좋습니다. 자세한 정보는 [지연 및 백오프 구성](retries.md#retries-delays-backoff)을 참조하세요.
+ **회로 차단기 모드를 비활성화합니다.** SDK는 기본적으로 각 서비스 클라이언트에 대한 토큰 버킷을 유지합니다. SDK가 요청을 시도하고 재시도 가능한 예외와 함께 실패하면 토큰 수가 감소하고, 요청이 성공하면 토큰 수가 증가합니다.
기본적으로이 토큰 버킷이 남은 토큰이 0개에 도달하면 회로가 끊어집니다. 회로가 끊어지면 SDK는 재시도와 첫 번째 시도에서 실패한 현재 및 후속 요청을 즉시 비활성화하여 예외를 발생시킵니다. SDK는 초기 시도가 토큰 버킷에 충분한 용량을 반환한 후 재시도를 다시 활성화합니다. 이 동작은 의도적인 것이며 서비스 중단 및 서비스 복구 중에 재시도 폭풍을 방지하도록 설계되었습니다.
SDK가 구성된 최대 시도까지 계속 재시도하도록 하려면 클라이언트 구성에서 `retryStrategy.tokenBucket.useCircuitBreakerMode` 속성을 false로 설정하여 회로 차단기 모드를 비활성화하는 것이 좋습니다. 이 속성을 false로 설정하면 SDK 클라이언트는 토큰 버킷이 추가 재시도를 중단하지 않고 충분한 용량에 도달할 때까지 대기하여 토큰이 0개 남아 있을 때 예외가 발생할 수 있습니다.
## `NoSuchMethodError` 또는 NoClassDefFoundError를 수정하려면 어떻게 해야 합니까?
이러한 오류는 가장 일반적으로 종속성 누락 또는 충돌로 인해 발생합니다. 자세한 정보는 [종속성 충돌을 해결하려면 어떻게 해야 합니까?](ts-faq-dep-conflict-resolution.md)을 참조하세요.
### 에 `NoClassDefFoundError` 대한가 표시됩니다. `okhttp3/coroutines/ExecuteAsyncKt`
이는 특히 OkHttp의 종속성 문제를 나타냅니다. 자세한 정보는 [애플리케이션의 OkHttp 버전 충돌 해결](ts-faq-dep-conflict-resolution.md#okhttp-dep-conflicts)을 참조하세요.
# 종속성 충돌을 해결하려면 어떻게 해야 합니까?
를 사용할 때 제대로 작동하려면 특정 AWS 및 타사 종속성이 AWS SDK for Kotlin필요합니다. 런타임에 이러한 종속성이 없거나 예상치 못한 버전인 경우 `NoSuchMethodError` 또는와 같은 오류가 표시될 수 있습니다`NoClassDefFoundError`. 이러한 종속성 문제는 일반적으로 두 그룹으로 나뉩니다.
+ SDK/Smithy 종속성 충돌
+ 타사 종속성 충돌
Kotlin 애플리케이션을 빌드할 때 Gradle을 사용하여 종속성을 관리할 수 있습니다. 프로젝트에 SDK 서비스 클라이언트에 대한 종속성을 추가하면 필요한 모든 관련 종속성이 자동으로 포함됩니다. 그러나 애플리케이션에 다른 종속성이 있는 경우 SDK에 필요한 종속성과 충돌할 수 있습니다. 예를 들어 SDK는 애플리케이션에서 사용할 수 있는 인기 있는 HTTP 클라이언트인 OkHttp를 사용합니다. 이러한 충돌을 발견하는 데 도움이 되도록 Gradle은 프로젝트의 종속성을 나열하는 유용한 작업을 제공합니다.
```
./gradlew dependencies
```
종속성 충돌이 발생하면 조치를 취해야 할 수 있습니다. 로컬 네임스페이스에 특정 버전의 종속성 또는 섀도우 종속성을 지정할 수 있습니다. Gradle 종속성 해결은 *Gradle 사용 설명서*의 다음 섹션에서 설명하는 복잡한 주제입니다.
+ [ 종속성 해결 이해 ](https://docs.gradle.org/current/userguide/dependency_resolution.html)
+ [ 종속성 제약 조건 및 충돌 해결 ](https://docs.gradle.org/current/userguide/dependency_constraints_conflicts.html)
+ [ 종속성 버전 정렬 ](https://docs.gradle.org/current/userguide/dependency_version_alignment.html)
## 프로젝트에서 SDK 및 Smithy 종속성 관리
SDK를 사용할 때는 일반적으로 해당 모듈이 버전 번호가 일치하는 다른 SDK 모듈에 의존한다는 점에 유의하세요. 예를 들어 `aws.sdk.kotlin:s3:1.2.3`는에 따라 `ws.sdk.kotlin:aws-http:1.2.3`달라지는 `aws.sdk.kotlin:aws-core:1.2.3`에 따라 달라집니다.
SDK 모듈은 특정 Smithy 모듈 버전도 사용합니다. Smithy 모듈 버전은 SDK 버전 번호와 동기화되지 않지만 SDK의 예상 버전과 일치해야 합니다. 예를 들어는에 의존할 `aws.sdk.kotlin:s3:1.2.3` 수 있으며`aws.smithy.kotlin:serde:1.1.1`,는에 의존`aws.smithy.kotlin:runtime-core:1.1.1`하는 등등입니다.
종속성 충돌을 방지하려면 모든 SDK 종속성을 함께 업그레이드하고 명시적인 Smithy 종속성에 대해서도 동일한 작업을 수행합니다. [Gradle 버전 카탈로그](setup-create-project-file.md)를 사용하여 버전을 동기화하고 SDK 버전과 Smithy 버전 간의 매핑에서 추측을 제거하는 것이 좋습니다.
SDK/Smithy 모듈의 마이너 버전 업데이트에는 [버전 관리 정책에](https://github.com/awslabs/aws-sdk-kotlin/blob/main/VERSIONING.md#versioning-policy) 설명된 대로 주요 변경 사항이 포함될 수 있습니다. 마이너 버전 간에 업그레이드할 때는 변경 로그를 주의 깊게 검토하고 런타임 동작을 철저히 테스트합니다.
## 애플리케이션의 OkHttp 버전 충돌 해결
[OkHttp](https://square.github.io/okhttp/)는 SDK가 기본적으로 JVM에서 사용하는 인기 있는 HTTP 엔진입니다. 애플리케이션에는 다른 OkHttp 버전을 가져오는 다른 종속성 또는 프레임워크가 포함될 수 있습니다. 이로 인해 `okhttp/coroutines/ExecuteAsyncKt` 또는와 같은 `okhttp3` 네임스페이스의 클래스에 `NoClassDefFoundError` 대한가 발생할 수 있습니다`okhttp3/ConnectionListener`. 이 경우 일반적으로 최신 버전을 선택하여 충돌을 해결해야 합니다. 이러한 충돌의 원인을 추적하는 데 도움이 되도록 Gradle은 유용한 작업을 제공합니다. 다음을 실행하여 모든 종속성을 나열할 수 있습니다.
```
./gradlew dependencies
```
예를 들어 SDK가 OkHttp에 의존`5.0.0-alpha.14`하고 Spring Boot와 같은 다른 종속성이 OkHttp에 의존`4.12.0`하는 경우를 사용해야 합니다`5.0.0-alpha.14 version`. Gradle에서 `constraints` 블록을 사용하여이 작업을 수행할 수 있습니다.
```
dependencies {
constraints {
implementation("com.squareup.okhttp3:okhttp:4.12.0")
}
}
```
또는 OkHttp 4.x를 사용해야 하는 경우 SDK는를 제공합니다`OkHttp4Engine`. Gradle을 구성하고 코드`OkHttp4Engine`에서를 사용하는 방법에 대한 자세한 내용은 [설명서를](https://github.com/smithy-lang/smithy-kotlin/tree/main/runtime/protocol/http-client-engines/http-client-engine-okhttp4) 참조하세요.