トラブルシューティングに関するよくある質問 - AWS SDK for Java 2.x

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

トラブルシューティングに関するよくある質問

AWS SDK for Java 2.x アプリケーションで を使用すると、このトピックに記載されているランタイムエラーが発生する可能性があります。根本原因を見つけてエラーを解決するには、こちらの提案を参考にしてください。

java.net.SocketException「: Connection reset」または「server failed to complete the response」エラーを修正するにはどうすればよいですか?

接続リセットエラーは、リクエストが完了する前にホスト AWS のサービス、、または仲介者 (NAT ゲートウェイ、プロキシ、ロードバランサーなど) が接続を閉じたことを示します。多くの原因があるため、ソリューションを見つけるには、接続が閉じられている理由を知る必要があります。通常、以下の項目により接続が閉じられます。

  • 接続は非アクティブです。 これはストリーミングオペレーションで一般的であり、データが一定期間ワイヤとの間で書き込まれていないため、仲介者が接続をデッドとして検出して閉じます。これを防ぐには、アプリケーションがデータを積極的にダウンロードまたはアップロードしていることを確認してください。

  • HTTP または SDK クライアントを閉じました。使用中はリソースを閉じないでください。

  • プロキシの設定ミス。問題が修正されたかどうかを確認するために設定したプロキシをバイパスしてみてください。これにより問題が修正された場合、プロキシは何らかの理由で接続を閉じています。特定のプロキシを調べて、接続を閉じている理由を特定します。

問題を特定できない場合は、影響を受ける接続の TCP ダンプをネットワークのクライアントエッジで実行してみてください (たとえば、制御するプロキシの後など)。

AWS エンドポイントが TCP RST (リセット) を送信していることがわかった場合は、影響を受けるサービスに連絡して、リセットが発生している理由を判断できるかどうかを確認します。問題が発生したときのリクエスト IDs とタイムスタンプを提供する準備をします。 AWS サポートチームは、アプリケーションが送受信しているバイト数とタイミングを正確に示すワイヤログの恩恵を受けることもあります。

「接続タイムアウト」を修正するにはどうすればよいですか?

接続タイムアウトエラーは、ホスト、 AWS のサービス、または仲介者 (NAT ゲートウェイ、プロキシ、ロードバランサーなど) が、設定された接続タイムアウト内にサーバーとの新しい接続を確立できなかったことを示します。以下の項目では、この問題の一般的な原因について説明します。

  • 設定された接続タイムアウトが低すぎます。デフォルトでは、 の接続タイムアウトは 2 秒です AWS SDK for Java 2.x。接続タイムアウトを低く設定しすぎると、このエラーが発生する可能性があります。推奨される接続タイムアウトは、リージョン内呼び出しのみを行う場合は 1 秒、クロスリージョンリクエストを行う場合は 3 秒です。

  • プロキシの設定ミス。問題が修正されたかどうかを確認するために設定したプロキシをバイパスしてみてください。これにより問題が解決した場合、プロキシが接続タイムアウトの理由になります。特定のプロキシを調べて、その原因を特定する

問題を特定できない場合は、影響を受けた接続の TCP ダンプをネットワークのクライアントエッジで (たとえば、制御するプロキシの後に) 実行して、ネットワークの問題を調査してください。

java.net.SocketTimeoutException「: 読み取りタイムアウト」を修正するにはどうすればよいですか?

読み取りタイムアウトエラーは、JVM が基盤となるオペレーティングシステムからデータを読み取ろうとしたが、SDK を介して設定された時間内にデータが返されなかったことを示します。このエラーは、オペレーティングシステム、 AWS のサービス、または仲介者 (NAT ゲートウェイ、プロキシ、ロードバランサーなど) が JVM が想定する時間内にデータを送信できない場合に発生する可能性があります。多くの原因があるため、ソリューションを見つけるには、データが返されない理由を知る必要があります。

影響を受ける接続の TCP ダンプをネットワークのクライアントエッジで実行してみてください (たとえば、制御するプロキシの後など)。

AWS エンドポイントが TCP RST を送信 (リセット) していることがわかった場合は、影響を受ける サービスにお問い合わせください。問題が発生したときのリクエスト IDs とタイムスタンプを提供する準備をします。 AWS サポートチームは、アプリケーションが送受信しているバイト数とタイミングを正確に示すワイヤログの恩恵を受けることもあります。

「HTTP リクエストを実行できません: プールからの接続を待っているタイムアウト」エラーを修正するにはどうすればよいですか?

このエラーは、リクエストが指定された最大時間内にプールから接続を取得できないことを示します。問題をトラブルシューティングするには、SDK クライアント側のメトリクスを有効にして Amazon CloudWatch にメトリクスを発行することをお勧めします。HTTP メトリクスは、根本原因を絞り込むのに役立ちます。以下の項目では、このエラーの一般的な原因について説明します。

  • 接続リーク。これを調査するには、LeasedConcurrencyAvailableConcurrency、および MaxConcurrencyメトリクスを確認します。に達するまで LeasedConcurrencyが増加するMaxConcurrencyが、減少しない場合は、接続リークが発生する可能性があります。リークの一般的な原因は、S3 getObjectメソッドなどのストリーミングオペレーションが閉じられていないことです。アプリケーションは、できるだけ早く入力ストリームからすべてのデータを読み取り、後で入力ストリームを閉じることをお勧めします。次の図は、接続リークの SDK メトリクスがどのように表示されるかを示しています。

    接続リークの可能性を示す CloudWatch メトリクスのスクリーンショット。
  • 接続プールの不足。 これは、リクエストレートが高すぎて、設定された接続プールのサイズがリクエストの需要を満たせない場合に発生する可能性があります。デフォルトの接続プールサイズは 50 で、プール内の接続が最大に達すると、HTTP クライアントは接続が利用可能になるまで受信リクエストをキューに入れます。次の図は、接続プールの不足に対して SDK メトリクスがどのようになるかを示しています。

    接続プールの不足がどのように見えるかを示す CloudWatch メトリクスのスクリーンショット。

    この問題を軽減するには、次のいずれかのアクションを実行することを検討してください。

    • 接続プールのサイズを大きくします。

    • 取得タイムアウトを長くします。

    • リクエストレートを遅くします。

    接続の最大数を増やすことで、クライアントスループットを向上させることができます (ネットワークインターフェイスが既に完全に使用されている場合を除きます)。ただし、最終的には、プロセスで使用されるファイル記述子の数に関するオペレーティングシステムの制限に達する可能性があります。ネットワークインターフェイスを既に完全に使用している場合、または接続数をさらに増やすことができない場合は、取得タイムアウトを長くしてみてください。この増加により、タイムアウトする前にリクエストが接続を取得する時間が長くなります。接続が解放されない場合でも、後続のリクエストはタイムアウトします。

    最初の 2 つのメカニズムを使用して問題を解決できない場合は、次のオプションを試してリクエストレートを遅くします。

    • 大量のトラフィックバーストがクライアントを過負荷にしないように、リクエストを滑らかにします。

    • への呼び出しをより効率的にします AWS のサービス。

    • リクエストを送信するホストの数を増やします。

  • I/O スレッドがビジーすぎます。これは、 で非同期 SDK クライアントを使用している場合にのみ適用されますNettyNioAsyncHttpClientAvailableConcurrency メトリクスが低くなく、接続がプールで使用可能であることを示しているConcurrencyAcquireDurationが、高い場合は、I/O スレッドがリクエストを処理できない可能性があります。将来の完了エグゼキュターRunnable:runとして を渡し、応答の将来の完了チェーンで時間のかかるタスクを実行していないことを確認してください。これにより、I/O スレッドがブロックされる可能性があります。そうでない場合は、 eventLoopGroupBuilderメソッドを使用して I/O スレッドの数を増やすことを検討してください。参考までに、NettyNioAsyncHttpClientインスタンスの I/O スレッドのデフォルトの数は、ホストの CPU コア数の 2 倍です。

  • TLS ハンドシェイクのレイテンシーが高い。AvailableConcurrency メトリクスが 0 に近く、 よりLeasedConcurrency小さい場合はMaxConcurrency、TLS ハンドシェイクのレイテンシーが高いことが原因である可能性があります。次の図は、TLS ハンドシェイクのレイテンシーが高い場合に SDK メトリクスがどのようになるかを示しています。

    TLS ハンドシェイクのレイテンシーが高いことを示す CloudWatch メトリクスのスクリーンショット。

    CRT に基づいていない Java SDK が提供する HTTP クライアントの場合は、TLS ログを有効にして TLS の問題をトラブルシューティングしてみてください。CRT ベースの HTTP クライアントの場合は AWS 、AWS CRT ログを有効にしてみてください。 AWS エンドポイントが TLS ハンドシェイクの実行に時間がかかると思われる場合は、影響を受ける サービスにお問い合わせください

NoClassDefFoundError、、NoSuchMethodErrorまたは を修正するにはどうすればよいですかNoSuchFieldError

NoClassDefFoundError は、実行時にクラスをロードできなかったことを示します。このエラーの最も一般的な原因は 2 つあります。

  • JAR が見つからないか、JAR の間違ったバージョンがクラスパスにあるため、クラスはクラスパスに存在しません。

  • 静的イニシャライザが例外をスローしたため、 クラスをロードできませんでした。

同様に、 NoSuchMethodErrorNoSuchFieldErrorは通常、JAR バージョンが一致しないためです。次の手順を実行することをお勧めします。

  1. 依存関係をチェックして、すべての SDK jar の同じバージョンを使用していることを確認します。クラス、メソッド、またはフィールドが見つからない最も一般的な理由は、新しいクライアントバージョンにアップグレードしても、古い「共有」 SDK 依存関係バージョンを引き続き使用する場合です。新しいクライアントバージョンでは、新しい「共有」 SDK 依存関係にのみ存在するクラスを使用しようとする場合があります。mvn dependency:tree または gradle dependencies (Gradle の場合) を実行して、SDK ライブラリのバージョンがすべて一致することを確認します。この問題を完全に回避するには、BOM (部品表) を使用して SDK モジュールバージョンを管理することをお勧めします。

    次の例は、混合 SDK バージョンの例を示しています。

    [INFO] +- software.amazon.awssdk:dynamodb:jar:2.20.00:compile [INFO] | +- software.amazon.awssdk:aws-core:jar:2.13.19:compile [INFO] +- software.amazon.awssdk:netty-nio-client:jar:2.20.00:compile

    のバージョンは 2.20.00、 のバージョンaws-coreは 2.13.19 dynamodbです。aws-core アーティファクトバージョンも 2.20.00 である必要があります。

  2. ログの早い段階でステートメントをチェックして、静的初期化の失敗が原因でクラスがロードに失敗したかどうかを確認します。クラスが初めてロードに失敗すると、クラスをロードできない理由を指定する、より有用な別の例外がスローされる場合があります。この潜在的に有用な例外は 1 回だけ発生するため、後のログステートメントではクラスが見つからないことが報告されます。

  3. デプロイプロセスをチェックして、アプリケーションとともに必要な JAR ファイルを実際にデプロイしていることを確認します。正しいバージョンで構築している可能性がありますが、アプリケーションのクラスパスを作成するプロセスは、必要な依存関係を除外しています。

SignatureDoesNotMatch「」エラーまたは「計算したリクエスト署名が指定した署名と一致しません」エラーを修正するにはどうすればよいですか?

SignatureDoesNotMatch エラーは、 によって生成された署名 AWS SDK for Java と によって生成された署名が一致し AWS のサービス ないことを示します。以下の項目では、潜在的な原因について説明します。

  • プロキシまたは仲介者がリクエストを変更します。たとえば、プロキシまたはロードバランサーは、SDK によって署名されたヘッダー、パス、またはクエリ文字列を変更する場合があります。

  • サービスおよび SDK は、それぞれが署名する文字列を生成するときに、リクエストをエンコードする方法が異なります。

この問題をデバッグするには、SDK のデバッグログ記録を有効にすることをお勧めします。エラーを再現し、SDK が生成した正規リクエストを見つけます。ログでは、正規リクエストには というラベルが付けられAWS4 Canonical Request: ...、署名する文字列には AWS4 String to sign: ... というラベルが付けられます。

たとえば、本稼働環境でしか再現できないため、デバッグを有効にできない場合は、エラーが発生したときにリクエストに関する情報をログに記録するロジックをアプリケーションに追加します。その後、その情報を使用して、デバッグログを有効にして統合テストで本番環境の外部でエラーをレプリケートできます。

署名する正規リクエストと文字列を収集したら、AWS 署名バージョン 4 の仕様と比較して、SDK が署名する文字列を生成した方法に問題がないかどうかを確認します。問題が発生した場合は、 への GitHub バグレポートを作成できます AWS SDK for Java。

何も問題が表示されない場合は、SDK の 文字列と 文字列を比較して、一部の が失敗レスポンス (Amazon S3 など) の一部として を AWS のサービス 返すことを示すことができます。これが利用できない場合は、影響を受けるサービスに連絡して、比較のために生成された正規リクエストと署名文字列を確認する必要があります。これらの比較は、サービスとクライアント間のリクエストやエンコードの違いを変更した可能性のある仲介者を特定するのに役立ちます。

リクエストの署名の詳細については、「 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 接続プールが閉じられたことを示します。以下の項目では、潜在的な原因について説明します。

  • SDK クライアントが途中で閉じられました。 SDK は、関連付けられたクライアントが閉じられたときにのみ接続プールを閉じます。使用中はリソースを閉じないでください。

  • java.lang.Errorがスローされました。などのエラーOutOfMemoryErrorにより、Apache HTTP 接続プールがシャットダウンします。エラースタックトレースがないかログを調べます。また、 Throwableまたは をキャッチするErrorが、エラーが発生しないように出力を嚥下する場所についてもコードを確認してください。コードでエラーが報告されない場合は、情報がログに記録されるようにコードを書き換えます。ログに記録された情報は、エラーの根本原因を特定するのに役立ちます。

  • 閉じられたDefaultCredentialsProvider#create()後に から返された認証情報プロバイダーを使用しようとしました。 はシングルトンインスタンスをDefaultCredentialsProvider#create返すため、閉じられてコードが resolveCredentialsメソッドを呼び出すと、キャッシュされた認証情報 (またはトークン) の有効期限が切れた後に例外がスローされます。

    次の例に示すように、 DefaultCredentialsProvider が閉じられている場所にコードを確認します。

    • シングルトンインスタンスは、 を呼び出すことで閉じられます。 DefaultCredentialsProvider#close().

      DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider.create(); // Singleton instance returned. AwsCredentials credentials = defaultCredentialsProvider.resolveCredentials(); // Make calls to AWS のサービス. defaultCredentialsProvider.close(); // Explicit close. // Make calls to AWS のサービス. // After the credentials expire, either of the following calls eventually results in a "Connection pool shut down" exception. credentials = defaultCredentialsProvider.resolveCredentials(); // Or credentials = DefaultCredentialsProvider.create().resolveCredentials();
    • try-with-resources ブロックDefaultCredentialsProvider#create()で を呼び出します。

      try (DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider.create()) { AwsCredentials credentials = defaultCredentialsProvider.resolveCredentials(); // Make calls to AWS のサービス. } // After the try-with-resources block exits, the singleton DefaultCredentialsProvider is closed. // Make calls to AWS のサービス. DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider.create(); // The closed singleton instance is returned. // If the credentials (or token) has expired, the following call results in the error. AwsCredentials credentials = defaultCredentialsProvider.resolveCredentials();

    DefaultCredentialsProvider.builder().build() コードがシングルトンインスタンスを閉じており、 を使用して認証情報を解決する必要がある場合は、 を呼び出して新しい非シングルトンインスタンスを作成しますDefaultCredentialsProvider

「AwsCredentialsProviderChain チェーン内のいずれかのプロバイダーから認証情報をロードできない」を修正するにはどうすればよいですか?

このエラーは、 がデフォルトの AWS 認証情報プロバイダーチェーン内の認証情報プロバイダーを通じて有効な認証情報を見つけ AWS SDK for Java 2.x られなかったことを示します。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 インスタンスの場合
  • IAM ロールを確認する: IAM ロールがインスタンスにアタッチされていることを確認します。

  • 断続的な IMDS 障害: 断続的な障害 (通常は数百ミリ秒) が発生した場合、これは通常、インスタンスメタデータサービス (IMDS) に到達する一時的なネットワークの問題を示します。

    解決方法

    • デバッグログ記録を有効にして障害のタイミングと頻度を分析する

    • 認証情報関連の障害に対してアプリケーションに再試行ロジックを実装することを検討する

    • インスタンスと IMDS エンドポイント間のネットワーク接続の問題を確認する

コンテナ環境の場合

タスクロール (Amazon ECS) またはサービスアカウント (Amazon EKS) が設定され、必要な環境変数が設定されていることを確認します。

ローカル開発用

環境変数、認証情報ファイル、または IAM Identity Center 設定が設定されていることを確認します。

ウェブ ID フェデレーションの場合
  • 設定の検証: ウェブ ID トークンファイルが存在し、必要な環境変数が設定されていることを確認します。

  • STS モジュールの依存関係がない: エラー が表示された場合はTo use web identity tokens, the 'sts' service module must be on the class path、STS モジュールを依存関係として追加する必要があります。これは、Amazon EKS Pod Identity またはその他のウェブ ID トークン認証を使用する場合に一般的です。

    解決策: STS モジュールをプロジェクトの依存関係に追加します。

    • <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>sts</artifactId> </dependency>

      一部のサービスでは、aws-query-protocol依存関係も必要になる場合があります。

      <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>aws-query-protocol</artifactId> </dependency>

ネットワークまたはプロキシの接続の問題

認証情報プロバイダーチェーンにConnection refusedエラーが表示された場合は、通常、SDK がエンドポイントに到達 AWS しようとするとネットワーク接続の問題が示されます。

解決方法

  • プロキシサーバーを使用している場合は、プロキシ設定を確認する

  • ネットワークが AWS エンドポイントへのアウトバウンド HTTPS 接続を許可していることを確認します。

  • デバッグログを有効にして詳細な接続試行を表示する

  • エンドポイントへのネットワークアクセスを検証curlするための などのツールを使用して接続をテストする AWS