Amazon Q Developer Agent for code transformation に関する問題のトラブルシューティング - Amazon Q Developer
Amazon Q がプロジェクトをアップロードできないのはなぜですか?Maven コマンドが失敗するのはなぜですか?Maven を PATH に追加するにはどうすればよいですか?Amazon Q がコードをビルドできないのはなぜですか?55 分経過後に変換が失敗したのはなぜですか?変換されたコードをダウンロードできないのはなぜですか?コード変換ログにアクセスするにはどうすればよいですか?変換ジョブ ID を見つけるにはどうすればよいですか?

Amazon Q Developer Agent for code transformation に関する問題のトラブルシューティング

以下の情報は、Amazon Q Developer Agent for code transformation の問題のトラブルシューティングに役立ちます。

Amazon Q がプロジェクトをアップロードできないのはなぜですか?

プロジェクトのアップロードに失敗した場合、次の問題のいずれかが原因である可能性があります。Amazon Q で表示されるエラーに対応するトピックを参照してください。

プロジェクトサイズを縮小する

コードを変換するために、Amazon Q はソースコード、プロジェクトの依存関係、ビルドログを含むプロジェクトアーティファクトを生成します。変換ジョブのプロジェクトアーティファクトサイズの上限は 2 GB です。プロジェクトアーティファクトのサイズに関連するエラーが発生した場合は、プロジェクトのサイズを小さくするか、より小さなプロジェクトを変換する必要があります。プロジェクトアーティファクトファイルのサイズは、コード変換ログで確認できます。詳細については、「コード変換ログにアクセスするにはどうすればよいですか?」を参照してください。

IDE でプロキシを設定する

コードを変換するために、Amazon Q はプロジェクトアーティファクトをサービス所有の Amazon S3 バケットにアップロードします。アップロードプロセスの一部では、SSL 証明書または TLS 証明書を使用して Amazon S3 と IDE 間の通信を確立します。プロキシサーバーを使用している場合、プロキシサーバーで使用される SSL 証明書または TLS 証明書は信頼されている必要があります。信頼されていない場合、Amazon Q はプロジェクトをアップロードできません。

プロキシまたは証明書に関連するエラーが発生した場合は、証明書を信頼するか、他のプロキシ設定を更新するように IDE またはオペレーティングシステムを設定する必要があります。

注記

また、組織のプロキシサーバーまたはファイアウォールの後ろにいる場合、証明書とは無関係の問題が発生する可能性があります。次の手順で証明書を設定しても問題が解決しない場合は、ネットワーク管理者に連絡して、IDE から Amazon S3 との通信が許可されていることを確認してください。詳細については、「Amazon S3 へのアクセスを許可する」を参照してください。

JetBrains の証明書を設定する

プロキシサーバーで使用される SSL 証明書または TLS 証明書を信頼するように JetBrains IDE の Java ランタイム環境 (JRE) を設定するには、SSL 証明書または TLS 証明書を JRE 内の cacerts ファイルにインポートする必要があります。cacerts ファイルは、HTTPS や SSL などのセキュアな接続に称される信頼されたルート証明書を含むファイルであり、JRE のセキュリティ設定の一部です。証明書をインポートする手順は次のとおりです。

注記

cacerts ファイルを変更する前にバックアップを作成することをお勧めします。ミスがあると、セキュアな接続に問題が発生する可能性があるためです。

  1. JRE 内の cacerts ファイルへのパスを特定します。JetBrains IDE に同梱されている内部 JRE 内の cacerts ファイルのパスは、オペレーティングシステムと使用している JetBrains IDE のバージョンによって異なります。

    以下は、一般的なオペレーティングシステムの cacerts ファイルへのパスの例です。オペレーティングシステムを選択すると、例が表示されます。

    注記

    <JetBrains Installation Folder> は、JetBrains 製品がインストールされているディレクトリを指します。このディレクトリは通常、インストールプロセス中に選択されます。

    jbr フォルダは、JetBrains IDE にバンドルされた JRE を表します。これは、JetBrains IDE での使用に合わせてカスタマイズされた JRE の特定のバージョンです。

    Windows

    Windows にインストールされている JetBrains IDE の cacerts ファイルパスは次のとおりです。

    <JetBrains Installation Folder>\jbr\bin\cacerts

    例えば、Windows に JetBrains IDE をデフォルトの場所にインストールした場合、パスは次のようになります。

    C:\Program Files\JetBrains\jbr\bin\cacerts
    macOS

    macOS にインストールされている JetBrains IDE の cacerts ファイルパスは次のとおりです。

    /Applications/JetBrains Toolbox/<version>/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts

    例えば、macOS に JetBrains IDE をデフォルトの場所にインストールした場合、パスは次のようになります。

    /Applications/JetBrains Toolbox/2022.3.4/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts
    Linux

    Linux にインストールされている JetBrains IDE の cacerts ファイルパスは次のとおりです。

    /opt/jetbrains/jbr/lib/security/cacerts

  2. cacerts ファイルにインポートする必要がある証明書を特定します。証明書ファイルの拡張子は通常 .cer、.crt、または .der です。追加すべき証明書がわからない場合は、ネットワーク管理者にお問い合わせください。

  3. 証明書を cacerts キーストアにインポートします。これは Java の keytool コマンドで行うことができます。

    1. コマンドプロンプトを開き、次のコマンドを使用します。

      keytool -import -alias <alias> -file <certificate_file> -keystore <path_to_cacerts>

    2. <alias> については、インポートする証明書の名前を追加しておけば、後で参照できます。このオプションはオプションです。

    3. <certificate_file> には、インポートする証明書へのパスを指定します。これは、証明書を含む .cer、.crt、または .der ファイルへのパスを指定してください。

    4. <path_to_cacerts> には、ステップ 1 で保存した cacerts キーストアファイルへのパスを指定します。これは、証明書をインポートするファイルです。

    例えば、Windows 上にある IntelliJ IDEA のバンドル JRE の cacerts キーストアに my_certificate.cer という名前の証明書をインポートし、証明書に myalias というエイリアスを付与する場合、 コマンドは次のようになります。

    keytool -import -alias myalias -file my_certificate.cer -keystore "C:\Program Files\JetBrains\IntelliJ IDEA 2022.3.2\jbr\bin\cacerts"

  4. インポートプロセス中に、キーストアパスワードの入力を求められます。cacerts キーストアのデフォルトのパスワードは changeit です。

  5. コマンドを実行すると、証明書を信頼するように求められます。証明書が信頼できることを確認してインポートを完了するには、yes と入力します。

  6. JRE に加えて、IDE 自体に証明書を追加する必要がある場合もあります。詳細については、JetBrains ドキュメントの「Server Certificates」を参照してください。

表示を増やす表示を減らす

Visual Studio Code の証明書を設定する

プロキシサーバーで使用される SSL 証明書または TLS 証明書を信頼するように Visual Studio Code を設定するには、オペレーティングシステムに次のプロキシ設定が設定されていることを確認してください。

macOS 上の Visual Studio Code で次のプロキシ設定を行います。

macOS キーチェーンに証明書を追加する

まだ追加していない場合は、プロキシサーバーが使用する証明書を macOS キーチェーンに追加する必要があります。キーチェーンに証明書を追加する方法については、「Keychain Access User Guide」の「Add certificates to a keychain using Keychain Access on Mac」を参照してください。

Mac CA VSCode 拡張機能をインストールする

Mac CA VSCode 拡張機能を使用すると、Amazon Q は Mac の Keychain Access に追加した証明書にアクセスできます。

拡張機能をインストールするには:

  1. VS Code 拡張機能ペインで mac-ca-vscode を検索し、[インストール] を選択します。

  2. VS Code を再起動します。

macOS で VS Code のプロキシ設定を更新する

次の設定を更新して、VS Code がプロキシに正しく設定されていることを確認します。

  1. VS Code で設定を開きます。

  2. 検索バーに「proxy」と入力します。

  3. [Http: Proxy] フィールドに、プロキシ URL を追加します。

  4. [Http: Proxy Strict SSL] のチェックボックスをオフにします。

  5. [Http: Proxy Support] ドロップダウンリストで、 [on] を選択します。

  6. 設定検索バーに「http.experimental.systemCertificatesV2」と入力します。[Http › Experimental: System Certificates V2] を選択します。

Windows 上の Visual Studio Code で次のプロキシ設定を行います。

Windows で信頼されたルート証明書として証明書を追加する

まだ追加していない使用していない場合は、プロキシサーバーが使用する証明書を Windows の信頼されたルート証明機関のストアに追加する必要があります。証明書を追加するには、次の手順を実行します。

  1. 検索ツールまたは Run コマンドウィンドウを開きます。

  2. 次のコマンドを入力して、Certificate Manager ツールを開きます。

    certmgr.msc

  3. [信頼されたルート証明機関] ストアを選択します。

  4. [証明書] を右クリックし、[すべてのタスク]、[インポート] の順に選択します。

  5. 指定された手順に従って、プロキシ証明書をインポートします。

  6. 証明書をインポートしたら、証明書が追加されていることを確認します。

    [信頼されたルート証明機関] ストアで、[証明書] をダブルクリックします。追加した証明書を右クリックし、[プロパティ] を選択します。[証明書の目的] で、[この証明書の目的をすべて有効にする] オプションが選択されていることを確認します。

Win-CA VSCode 拡張機能をインストールする

Win-CA VSCode 拡張機能により、Amazon Q は Windows で信頼されたルート証明書に追加した証明書にアクセスできます。

拡張機能をインストールするには:

  1. VS Code 設定ペインで「win-ca 」を検索します。

  2. [Inject] ドロップダウンリストで、[append] を選択します。

Windows の VS Code でプロキシ設定を更新する

次の設定を更新して、VS Code がプロキシに正しく設定されていることを確認します。

  1. VS Code で設定を開きます。

  2. 検索バーに「proxy」と入力します。

  3. [Http: Proxy] フィールドに、プロキシ URL を追加します。

  4. [Http: Proxy Strict SSL] のチェックボックスをオフにします。

  5. [Http: Proxy Support] ドロップダウンリストで、 [on] を選択します。

  6. 設定検索バーに「http.experimental.systemCertificatesV2」と入力します。[Http › Experimental: System Certificates V2] を選択します。

  7. VS Code を再起動します。

Amazon S3 へのアクセスを許可する

変換の間、Amazon Q Developer Agent for code transformation はコードをサービス所有の Amazon S3 バケットにアップロードします。ネットワークまたは組織が Amazon S3 へのアクセスを設定していない場合、Amazon Q はプロジェクトをアップロードできません。

Amazon Q がプロジェクトをアップロードできるようにするには、プロキシ設定や Data Lost Prevention (DLP) ポリシーなどのネットワークコンポーネントが Amazon S3 へのアクセスを許可するように設定されていることを確認します。また、Amazon Q がプロジェクトをアップロードする Amazon S3 バケットを許可リストに登録する必要が生じる場合もあります。詳細については、「Amazon Q リソースのデータ境界」を参照してください。

大規模なプロジェクトを変換する場合、DLP ポリシーなどのネットワークコンポーネントが Amazon S3 バケットを許可リストに登録するように設定されていないと、遅延が発生し、アップロードが成功しない可能性があります。バケットを許可リストに登録しない場合、Amazon Q がバケットをアップロードできるように、より小さなプロジェクトを変換する必要がある場合があります。

Maven コマンドが失敗するのはなぜですか?

以下は、JetBrains IDE および Visual Studio Code IDE で発生する可能性のある Maven の設定の問題です。問題に対処しても Maven エラーが表示される場合は、プロジェクトに問題がある可能性があります。エラーログの情報を使用して、プロジェクトに関する問題に対処し、プロジェクトをもう一度変換してみてください。

JetBrains で Maven の設定を更新する

JetBrains での変換が Maven コマンドの問題が原因で失敗すると、エラーログが [Run] タブに表示されます。ログの情報を使用して問題に対処します。以下は、対処する必要がある問題の例です。

  • Maven のホームパスが [Bundled] に設定されていることを確認します。[Settings] ダイアログボックスで、[Build, Execution, Deployment] セクションを展開します。[Build Tools] セクションを展開し、[Maven] を展開します。[Maven home path] ドロップダウンリストで、[Bundled] を選択します。

  • Java ランタイム環境 (JRE) でプロジェクト JDK が使用されていることを確認します。[Settings] ダイアログボックスで、[Build, Execution, Deployment] セクションを展開します。[Maven] を展開して [Runner] を選択します。[JRE] ドロップダウンリストで、[Use Project JDK] を選択します。

  • 「Maven」が有効になっていることを確認します。[Settings] に移動し、[Plugins] を選択します。「Maven」を検索して Maven プラグインを選択します。[Enable] ボタンが表示された場合は、選択して Maven を有効にします。

Visual Studio Code で Maven の設定を更新する

VS Code での変換が Maven コマンドの問題が原因で失敗すると、エラーログを含むテキストファイルが新しいタブで開きます。ログの情報を使用して問題に対処します。

次のオプションのいずれかが設定されていることを確認します。

  • プロジェクトのプロジェクトルートフォルダに Maven ラッパーが含まれている

  • Amazon Q でサポートされている Maven のバージョンが PATH で利用可能になっている

詳細については、「Maven を PATH に追加するにはどうすればよいですか?」を参照してください。

Maven を PATH に追加するにはどうすればよいですか?

Maven ラッパーを使用せずに VS Code でコードを変換するには、Maven をインストールして PATH 変数に追加する必要があります。

Maven が既に正しくインストールされているかどうかを確認するには、Visual Studio Code の外部にある新しい OS ターミナルで mvn -v を実行します。Maven のバージョンが出力に表示されるはずです。

Visual Studio Code ターミナルで出力が得られるのに OS ターミナルで出力が得られない場合、またはコマンドが見つからない場合は、Maven を PATH に追加する必要があります。

Maven を PATH に追加するには、ご利用のマシン向けの手順を実行します。

macOS

Maven を macOS PATH に追加するには、次の手順を実行します。

  1. Maven インストールディレクトリ、または Maven をインストールしたフォルダを見つけ、そのフォルダへのパスを保存します。

  2. 任意のエディタでシェルの設定ファイルを開きます。最近の macOS バージョンでは、デフォルトのシェルは zsh で、デフォルトの設定ファイルは ~/.zshrc にあります。

    設定ファイルに次の行を追加します。M2_HOME の値は、ステップ 1 で保存したパスに設定します。

    export M2_HOME="your Maven installation directory"
export PATH="${M2_HOME}/bin:${PATH}"

    これらのコマンドにより、mvn コマンドがすべてのターミナルで使用できるようになります。

  3. すべての OS ターミナルウィンドウを閉じて、すべての Visual Studio Code インスタンスを終了します。

  4. Maven が PATH に追加されたことを確認するには、新しい OS ターミナルを開き、次のコマンドを実行します。

    mvn -v

    Maven のバージョンが出力に表示されるはずです。

  5. Maven 出力が表示されたら、Visual Studio Code を再起動します。マシンを再起動する必要がある場合もあります。Visual Studio Code ターミナルを開き、次のコマンドを実行します。

    mvn -v

    出力は、ステップ 4 の出力と同じであるはずです。Visual Studio Code 出力が異なる場合は、以下を試して設定が正しいことを確認します。

    • Visual Studio Code で PATH 変数を確認します。IDE 拡張機能によって、ローカルの PATH 変数とは異なるPATHように が変更されている可能性があります。拡張機能をアンインストールして、PATH から削除します。

    • Visual Studio Code でデフォルトのシェルを確認します。zsh 以外に設定している場合は、シェルに対して上記のステップを繰り返します。

Windows

Maven を Windows PATH に追加するには、次の手順を実行します。

  1. Maven インストールディレクトリ、または Maven をインストールしたフォルダを見つけ、そのフォルダへのパスを保存します。

  2. [環境変数] ウィンドウを開きます。

    1. Windows キーを押して検索バーを開きます。

    2. 「Edit environment variables for your account」と入力して選択します。

  3. [環境変数] ウィンドウで、Path 変数を探します。Path 変数が既にある場合は、[編集...] を選択して更新します。Path 変数がない場合は、[新規...] を選択して追加します。

  4. 表示される [環境変数名の編集] ウィンドウで、既存のパスをダブルクリックして編集するか、[新規] を選択して新しいパスエントリを追加します。

    既存の Maven パスエントリを、ステップ 1 で保存したパスに置き換えるか、パスを新しいエントリとして追加します。パスの最後に、次の例のように、サフィックスとして \bin を追加します。

    C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin

  5. [OK] を選択してパスエントリを保存し、[環境変数] ウィンドウで再度 [OK] を選択します。

  6. 新しいコマンドプロンプトを開き、次のコマンドを入力します。

    mvn -v

    Maven のバージョンが出力に表示されるはずです。

Amazon Q がコードをビルドできないのはなぜですか?

Amazon Q がコードをビルドする際に変換が失敗する場合は、Amazon Q がコードをビルドする環境に合わせてプロジェクトが正しく設定されていない可能性があります。ビルド設定またはコード実装を更新する必要があるかもしれません。

Amazon Q が提供するビルドログ出力を確認して、プロジェクトに加えられる変更があるかどうかを判断します。以下は、Amazon Q によるコードのビルドを妨げる可能性のある一般的な問題です。

pom.xml の絶対パスを削除する

pom.xml ファイルに絶対パスがある場合、Amazon Q は関連するファイルを見つけることができず、その結果、コードをビルドできない可能性があります。

以下は、pom.xml ファイルに含まれている可能性のある絶対パスの例です。

<toolspath>
    <path>/Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home/lib/tools.jar</path>
</toolspath>

絶対パスを使用する代わりに、ポインタを使用して相対パスを作成できます。以下は、前の絶対パスを相対パスに置き換える方法の例です。

<toolspath>
    <path>${java.home}/../lib/tools.jar</path>
</toolspath>

ユニットテストのローカルデータベースまたは外部データベースを削除する

Amazon Q は、コードをビルドする際、プロジェクト内のすべてのユニットテストを実行します。ユニットテストがローカルデータベースまたは外部データベースを呼び出すと、Amazon Q はデータベースにアクセスできず、ビルドが失敗します。ビルドが失敗しないようにするには、変換を送信する前に、ユニットテストからデータベース呼び出しを削除するか、ユニットテストを削除する必要があります。

55 分経過後に変換が失敗したのはなぜですか?

コード変換ジョブが 55 分経過後に失敗した場合、コードのビルド時間がビルドの時間制限を超えている可能性があります。現在、コードのビルドには 55 分の制限があります。

ローカルビルドに 55 分以上かかる場合、コードを変換するには、プロジェクトのビルド時間を短縮します。ローカルビルドがコード変換を使用したビルドよりも速い場合は、環境が変わると障害が発生したり、かかる時間が長くなったりする可能性のあるタスクがないかプロジェクトをチェックします。長時間の実行が必要なテストケースを無効にすることを検討してください。また、セキュアな IDE 環境やインターネットから利用できないリソースにアクセスする試みに、タイムアウトを使用することも検討してください。

変換されたコードをダウンロードできないのはなぜですか?

変換の完了後にコードをダウンロードできない場合は、次のいずれかの問題が原因である可能性があります。Amazon Q で表示されるエラーに対応するトピックを参照してください。

プロジェクトサイズを縮小する

変換が完了すると、Amazon Q は、アップグレードされたコードを含む 差分と、変更に関する情報が記載された変換の概要を含む出力アーティファクトを生成します。IDE で出力アーティファクトをダウンロードするには、出力アーティファクトが 1 GB 以下である必要があります。

出力アーティファクトが制限を超えると、アップグレードされたコードまたは変換の概要をダウンロードできなくなります。出力アーティファクトが大きくならないように、小さなプロジェクトを変換してみてください。問題が解決しない場合は、AWS Support までお問い合わせください。Amazon Q を使用した AWS Supportへの問い合わせについては、「Amazon Q Developer を使用して AWS Supportとチャットする」を参照してください。

24 時間以内にコード差分をダウンロードする

アップグレードされたコードを含むコード差分ファイルは、変換完了後 24 時間のみ入手できます。変換が完了してから 24 時間以上経過している場合は、変換を再スタートして差分ファイルをダウンロードしてください。

IDE でプロキシを設定する

Amazon Q Developer Agent for code transformation は、サービス所有の Amazon S3 バケットからアップグレードされたコードをダウンロードします。ダウンロードプロセスの一部では、SSL 証明書または TLS 証明書を使用して Amazon S3 と IDE 間の通信を確立します。プロキシサーバーを使用している場合、プロキシサーバーで使用される SSL 証明書または TLS 証明書は信頼されている必要があります。信頼されていない場合、Amazon Q はプロジェクトをアップロードできません。

コードをダウンロードするには、証明書を信頼するように IDE を設定したり、他のプロキシ設定を更新したりする必要がある場合があります。プロキシ設定の更新の詳細については、「IDE でプロキシを設定する」を参照してください。

JetBrains プロキシ設定のワイルドカード文字を削除する

JetBrains IDE でプロキシ設定を行っている場合、アップグレードされたコードのダウンロード時に次のエラーが表示されることがあります。

software.amazon.awssdk.core.exception.SdkClientException: 
Unable to execute HTTP request: Dangling meta character '*' near index 0

これは、IDE の [No proxy for] フィールドにワイルドカード文字 (*) が存在することが原因で発生する可能性があります。Amazon Q Developer Agent for code transformation で使用される Java SDK は、このフィールドのワイルドカードエントリをサポートしていません。

コードをダウンロードするには、[No proxy for] フィールドからワイルドカードを削除し、IDE を再起動します。プロキシをバイパスするホストを指定する必要がある場合は、ワイルドカードの代わりに正規表現を使用します。JetBrains IDE のプロキシ設定を更新するには、JetBrains ドキュメントの「HTTP Proxy」を参照してください。

コード変換ログにアクセスするにはどうすればよいですか?

JetBrains でログにアクセスする

JetBrains ログファイルにアクセスする方法については、JetBrains ドキュメントの「Locating IDE log files」を参照してください。

Amazon Q Developer Agent for code transformation で JetBrains によって発行されたログを検索するには、IDE ログで次の文字列を検索します。

software.aws.toolkits.jetbrains.services.codemodernizer

コード変換ログは、上記の文字列で始まります。Maven によって生成されたログは [Run] タブに表示され、ログエントリの前後に上記の文字列があります。

Visual Studio Code でログにアクセスする

VS Code で Amazon Q Developer Agent for code transformation によって出力されたログを検索するには、次の手順を実行します。

  1. 上部のナビゲーションバーで [ビュー] を選択し、[コマンドパレット] を選択します。

  2. 表示されるコマンドパレットで「Amazon Q: View Logs」を検索します。

  3. ログが IDE で開きます。ログファイルで CodeTransformation を検索するには、CMD + F または Control + F を使用します。

VS Code のコード変換のログには、CodeTransformation: というプレフィックスが付いています。以下は、Maven コピー依存関係エラーに対して VS Code で生成されたログの例です。

2024-02-12 11:29:16 [ERROR]: CodeTransformation: Error in running Maven copy-dependencies command mvn = /bin/sh: mvn: command not found

変換ジョブ ID を見つけるにはどうすればよいですか?

JetBrains でジョブ ID を見つける

JetBrains で変換ジョブ ID を見つけるには、[変換ハブ] の [変換の詳細] タブに移動し、[ジョブステータスの表示] (時計) アイコンをクリックします。

Visual Studio Code でジョブ ID を見つける

VS Code で変換ジョブ ID を検索するには、[変換ハブ] に移動し、[ジョブステータスの表示] (時計) アイコンをクリックします。