# Transforming Java applications with Amazon Q Developer **Note** AWS Transform custom now available for Java upgrades. Agentic AI that handles version upgrades, SDK migration, and more, and improves with every execution. [Get started](https://docs.aws.amazon.com/transform/latest/userguide/custom-get-started.html) Amazon Q supports the following types of transformations for Java applications: + Java language and dependency version upgrades + Embedded SQL conversion for Oracle to PostgreSQL database migration To get started, see the topic for the type of transformation you'd like to perform. **Topics** + [ ## Quotas ](#quotas-java-transformation-ide) + [ # Upgrading Java versions with Amazon Q Developer ](code-transformation.md) + [ # Converting embedded SQL in Java applications with Amazon Q Developer ](transform-sql.md) + [ # Transforming code on the command line with Amazon Q Developer ](transform-CLI.md) + [ # Viewing transformation job history ](transformation-job-history.md) + [ # Troubleshooting issues with Java transformations ](troubleshooting-code-transformation.md) ## Quotas Java application transformations with Amazon Q in the IDE and command line maintain the following quotas: + **Lines of code per job** – The maximum number of code lines that Amazon Q can transform in a given transformation job. + **Lines of code per month** – The maximum number of code lines that Amazon Q can transform in a month. + **Concurrent jobs** – The maximum number of transformation jobs you can run at the same time. This quota applies to all transformations in the IDE, including [.NET transformations in Visual Studio](transform-dotnet-IDE.md). + **Jobs per month** – The maximum number of transformation jobs you can run in one month. | Resource | Quotas | | --- | --- | | Lines of code per job | Free tier: 1000 lines of code | | Lines of code per month | Free tier: 2000 lines of code | | Concurrent jobs | 1 job per user 25 jobs per AWS account | | Jobs per month | Pro tier: 1000 jobs Free tier: 100 jobs | # Upgrading Java versions with Amazon Q Developer Amazon Q Developer can upgrade your Java applications to newer language versions in the integrated development environment (IDE). Changes Amazon Q can make to upgrade your code include updating deprecated code components and APIs as well as upgrading libraries, frameworks, and other dependencies in your code. To transform your code, Amazon Q first builds your code in the source language version and verifies that it has the information necessary to perform the transformation. After Amazon Q successfully transforms your code, you verify and accept the changes in your IDE. Since Amazon Q Developer makes the minimal changes necessary to make your upgraded code compatible with the target JDK, an additional transformation is required to upgrade your project's libraries and dependencies. For more information about how Amazon Q transforms your code, see [How Amazon Q Developer transforms code for Java language upgrades](how-CT-works.md). **Topics** + [ ## Supported Java upgrades and IDEs ](#supported-languages-IDEs) + [ ## Step 1: Prerequisites ](#java-upgrade-prerequisites) + [ ## Step 2: Configure your project ](#configure-project) + [ ## Step 3: Create a dependency upgrade file (optional) ](#create-dependency-upgrade-file) + [ ## Step 4: Transform your code ](#transform-code-java) + [ # How Amazon Q Developer transforms code for Java language upgrades ](how-CT-works.md) ## Supported Java upgrades and IDEs Amazon Q currently supports the following Java source code versions and target versions for transformations. Transforming code to the same Java version includes upgrading libraries and other dependencies in the source code version. **Supported Java upgrades** | Source code version | Supported target versions | | --- | --- | | Java 8 | Java 17 and Java 21 | | Java 11 | Java 17 and Java 21 | | Java 17 | Java 17 and Java 21 | | Java 21 | Java 21 | Amazon Q supports Java upgrades in the following IDEs: + Modules in JetBrains IDEs + Projects and workspaces in Visual Studio Code ## Step 1: Prerequisites Before you continue, make sure you’ve completed the steps in [Set up Amazon Q in your IDE](q-in-IDE-setup.md). Make sure that the following prerequisites are met before you begin a Code Transformation job: + Your project is written in a [supported Java version](#supported-languages-IDEs) and is built on Maven. + Your project successfully builds with Maven in your IDE. Maven 3.8 or later is currently supported. + Your project source JDK is available locally and is the version of your source code. For example, if you are transforming Java 8 code, your local JDK installation should be JDK 8. + Your project builds in 55 minutes or less. + Your project is configured correctly, and the correct JDK version is specified. For more information, see [Step 2: Configure your project](#configure-project). + Your project doesn't require access to resources on your private network, including a virtual private cloud (VPC) or on-premise network. For example, if your project contains unit tests that connect to a database in your network, the transformation will fail. + Your project doesn't use plugins that package languages other than Java in your Java project. For example, if your project uses the [frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin) for executing front-end JavaScript code in addition to your Java source code, the transformation will fail. + Your local network allows uploads to Amazon S3 buckets that Amazon Q uses to transform your code. For more information, see [Allow access to Amazon S3 buckets in data perimeters](firewall.md#data-perimeters). + Your application only uses UTF-8 characters. If your application uses non-UTF-8 characters, Amazon Q will still attempt to transform your code. ## Step 2: Configure your project To configure your project, use the following information for the IDE you're using. ### Configure a project in JetBrains To configure your project in JetBrains, you might need to specify the following project and module settings. If your modules use the same JDK and language level as your project, you don't need to update module settings. + Project SDK – The JDK used to compile your project. + Project language level – The Java version used in your project. + Module SDK – The JDK used to compile your module. + Module language level – The Java version used in your module. + Maven Runner JRE – The JDK you build your module with. **Update project and module settings** To update your SDK and language level settings for your project or module, complete the following steps: 1. From your JetBrains IDE, choose **File** and then **Project Structure**. 1. The Project Structure window opens. Under **Project Settings**, choose **Project**. 1. To update your project JDK, choose from the dropdown list next to **SDK**. 1. To update your project language, choose from the dropdown next to **Language level**. 1. Under **Project Settings**, choose **Modules**. 1. To update your module JDK, choose from the dropdown list next to **SDK**. 1. To update your module language, choose from the dropdown next to **Language level**. For more information, see [Project structure settings](https://www.jetbrains.com/help/idea/project-settings-and-structure.html) and [Module structure settings](https://www.jetbrains.com/help/idea/configure-modules.html) in the JetBrains documentation. **Update Maven settings** To update your Maven Runner JRE, complete the following steps: 1. From your JetBrains IDE, choose the gear icon, and then choose **Settings** in the menu that appears. 1. In the **Settings** window, choose **Build, Execution, Deployment**, then **Build Tools**, then **Maven**, and then **Runner**. 1. In the JRE field, choose the JDK used to build the module you're transforming. ### Configure a project in VS Code To configure your project in VS Code, your project must contain the following: + A `pom.xml` file in the project root folder + A `.java` file in the project directory If your project contains a Maven wrapper executable (`mvnw` for macOS or `mvnw.cmd` for Windows), make sure it’s at the root of your project. Amazon Q will use the wrapper, and no other Maven configuration is necessary. If you aren’t using a Maven wrapper, install Maven. For more information, see [Installing Apache Maven](https://maven.apache.org/install.html) in the Apache Maven documentation. After installing Maven, add it to your `PATH` variable. For more information, see [How do I add Maven to my `PATH`?](troubleshooting-code-transformation.md#add-maven-to-path) Your Java `runtime` variable should also be pointing to a JDK and not to a JRE. To confirm your configuration is correct, run `mvn -v`. The output should show your Maven version and the `runtime` variable pointing to the path to your JDK. ## Step 3: Create a dependency upgrade file (optional) You can provide Amazon Q with a *dependency upgrade file*, a YAML file that lists your project's dependencies and which versions to upgrade to during a transformation. By providing a dependency upgrade file, you can specify third and first party dependencies that Amazon Q might not otherwise know to upgrade. First party dependencies refer to the libraries, plugins, and frameworks that your organization maintains and are only available locally or on your organization’s private network. Amazon Q is able to access your first party dependencies when it performs builds in your local environment. For more information, see [Building code in your local environment](how-CT-works.md#java-local-builds). Third party dependencies are publicly available or open source dependencies that aren’t unique to your organization. You can specify first party dependencies you want to upgrade in a YAML file, and Amazon Q upgrades them during the JDK upgrade (for example, Java 8 to 17). You can initiate a separate transformation (17 to 17 or 21 to 21) after the initial JDK upgrade to upgrade third-party dependencies. Once Amazon Q performs a minimum JDK upgrade, you can initiate a separate transformation to upgrade all third party dependencies. Alternatively, you can specify third party dependencies and their versions in a YAML file to only upgrade those dependencies during the library upgrade transformation. Amazon Q will prompt you to provide a dependency upgrade file during the transformation. If you want to provide one, first make sure you've configured the file properly. The following fields are required in the YAML file: + name - The name of the dependency upgrade file. + description (optional) - A description of the dependency upgrade file, and for which transformation. + dependencyManagement - Contains the list of dependencies and plugins to upgrade. + dependencies - Contains the name and version of the libraries to upgrade. + plugins - Contains the names and versions of the plugins to upgrade. + identifier - The name of the library, plugin, or other dependency. + targetVersion - The version of the dependency to upgrade to. + versionProperty (optional) - The version of the dependency you're defining, as set with the `properties` tag in your application's `pom.xml` file. + originType - Whether the dependency is first or third party, specified by either FIRST\$1PARTY or THIRD\$1PARTY. Following is an example of a dependency upgrade YAML file, and the required configuration for Amazon Q to parse: ``` name: dependency-upgrade description: "Custom dependency version management for Java migration from JDK 8/11/17 to JDK 17/21" dependencyManagement: dependencies: - identifier: "com.example:library1" targetVersion: "2.1.0" versionProperty: "library1.version" # Optional originType: "FIRST_PARTY" - identifier: "com.example:library2" targetVersion: "3.0.0" originType: "THIRD_PARTY" plugins: - identifier: "com.example.plugin" targetVersion: "1.2.0" versionProperty: "plugin.version" # Optional originType: "THIRD_PARTY" ``` ## Step 4: Transform your code To test your IDE setup, download and unzip the sample project, and complete the following steps for your IDE. If you are able to view the proposed changes and transformation summary, you are ready to transform your own code project. If the transformation fails, your IDE is not configured correctly. To address configuration issues, review [Step 2: Configure your project](#configure-project) and [Troubleshooting](troubleshooting-code-transformation.md). **Note** Do not turn off, close, or put your local machine to sleep during the code transformation. The initial and validation builds use the client-side environment, which requires a stable network connection. To upgrade the language version of your code project or module, complete the following steps for your IDE. ------ #### [ JetBrains ] 1. Open the module that you want to upgrade in JetBrains. Make sure you’ve successfully built your project in the IDE. 1. Choose the Amazon Q logo, and ask Amazon Q to transform your application in the chat panel that opens. 1. A **Transform your application** pop-up appears. Choose the project that you want to upgrade from the dropdown list, and then choose **Transform**. 1. Amazon Q prompts you to provide an upgrade dependency file. If you have configured a YAML with the dependencies and version to upgrade to, add your file. Amazon Q will validate the file to ensure it's configured correctly. If you get an error, review the format and required fields described in [Step 3: Create a dependency upgrade file (optional)](#create-dependency-upgrade-file). 1. Amazon Q begins the transformation. You can view progress on the **Transformation details** tab. 1. After the transformation is complete, you can verify the upgraded code before updating your project. To view the new code, go to the **Transformation details** tab and then choose **View diff**. In the **Apply patch** window that appears, choose a file to open a diff view with your source code and upgraded code. 1. To accept the changes that Amazon Q made, choose **View diff** to open the **Apply patch** window. Select all the updated files, and choose **OK** to update your project in place. 1. To get details about how your code was upgraded and suggested next steps, on the **Transformation details** tab, choose **View transformation summary**. ------ #### [ Visual Studio Code ] 1. Open the project or workspace that you want to upgrade in VS Code. Make sure that you’ve successfully built your project in the IDE. 1. Choose the Amazon Q logo, and ask Amazon Q to transform your application in the chat panel that opens. 1. Choose the project that you want to upgrade from the search bar at the top of the IDE. 1. If Amazon Q can’t find the version of your source code, it prompts you to choose your code version. Choose the version that your source code is written in, and then choose **Transform** in the pop-up to proceed. 1. If prompted, enter the `JAVA_HOME` path to your JDK. For more information, see [Configure your VS Code project](#configure-vsc). 1. Amazon Q prompts you to provide an upgrade dependency file. If you have configured a YAML with the dependencies and version to upgrade to, add your file. Amazon Q will validate the file to ensure it's configured correctly. If you get an error, review the format and required fields described in [Step 3: Create a dependency upgrade file (optional)](#create-dependency-upgrade-file). 1. Amazon Q begins the transformation. You can view progress on the **Transformation Hub** tab. 1. After the transformation is complete, the **Proposed Changes** tab opens. To verify the upgraded code before updating your project, choose **Download proposed changes**. Choose a file to open a diff view with your source code and upgraded code. 1. To accept the changes Amazon Q made, go to the **Proposed Changes** tab and choose **Accept**. 1. To get details about how your code was upgraded and suggested next steps, on the **Transformation Hub**, choose the **Views and More Actions** ellipsis button, and then choose **Show Transformation Summary**. ------ # How Amazon Q Developer transforms code for Java language upgrades To transform your code, Amazon Q Developer generates a transformation plan that it uses to upgrade the code language version of your project. After transforming your code, it provides a transformation summary and a file diff for you to review changes before accepting them. Since Amazon Q Developer makes the minimal changes necessary to make your upgraded code compatible with the target JDK, an additional transformation is required to upgrade your project's libraries and dependencies. The following sections provide more details on how Amazon Q performs the transformation. ## Building your code and creating a transformation plan To begin transforming your code, Amazon Q builds your project locally and generates a build artifact that contains your source code, project dependencies, and build logs. After generating the build artifact, Amazon Q builds your code in a secure build environment and creates a transformation plan, which is customized to the project or module you’re upgrading. The transformation plan outlines the specific changes Amazon Q will attempt to make, including new dependency versions, major code changes, and suggested replacements for deprecated code. These changes are based on the preliminary build of your code, and might change during the transformation. ## Transforming your code To transform your code, Amazon Q attempts to upgrade your code to the target Java version based on the proposed changes in the transformation plan. As it makes changes, it re-builds and runs existing unit tests in your source code to iteratively fix any encountered errors. The JDK upgrade can be made from the following source code version to the target version: + Java 8 to 17 + Java 8 to 21 + Java 11 to 17 + Java 11 to 21 + Java 17 to 21 Amazon Q makes the minimal changes necessary to make your code compatible with the target Java version. Once Amazon Q performs a minimum JDK upgrade, you can initiate a separate transformation to upgrade all third party dependencies. Alternatively, you can specify third party dependencies and their versions in a YAML file to only upgrade those dependencies during the library upgrade transformation. Amazon Q attempts to make the following changes when upgrading your code: + Update deprecated code components according to the target Java version recommendations + Upgrade popular libraries and frameworks to a version compatible with the target Java version. This includes updating the following libraries and frameworks to their latest available major versions: + Apache Commons IO + Apache HttpClient + bc-fips + Cucumber-JVM + Hibernate + jackson-annotations + JakartaEE + Javax + javax.servlet + jaxb-api + jaxb-impl + jaxen + jcl-over-slf4j + json-simple + jsr305 + junit + junit-jupiter-api + Log4j + Micronaut + Mockito + mockito-core + Okio + PowerMockito + Quarkus + slf4j + slf4j-api + Spring Boot + Spring Framework + Spring Security + Swagger + testng **Note** Do not turn off or close your local machine during the code transformation because client-side build requires a stable network connection. ## Building code in your local environment During a transformation, Amazon Q performs verification builds in your local environment. Amazon Q transforms your code on the server side in multiple steps. After each step, Amazon Q sends the code to your local environment to build and test the changes it made. The code is then sent back to the server side to continue the transformation. The build in your local environment helps verify the transformed code by allowing Amazon Q to run tests that require access to private resources. To minimize security risks associated with building AI-generated code in your local environment, Amazon Q reviews and updates the code it generates to address security concerns. ## Reviewing the transformation summary and accepting changes After the transformation is complete, Amazon Q provides a transformation summary with details about the changes it made, including the status of the final build which indicates whether your entire project was upgraded. You can also view a build log summary to understand any issues that prevented Amazon Q from building your code in the upgraded version. The transformation summary additionally includes the differences between the changes proposed in the transformation plan and the changes Amazon Q ultimately made to upgrade your code, and any additional changes that weren’t in the original plan. After you review the transformation summary, you can view the changes Amazon Q is proposing in a file diff view. Any code changes Amazon Q suggests will not affect your current project files until you accept the changes. The transformed code is available up to 30 days after the transformation completes. ## Completing partially successful transformations Depending on the complexity and specifics of your codebase, there might be instances where the transformation is partially successful. This means that Amazon Q was able to transform only certain files or areas of code in your project. In this case, you have to manually update the remaining code for your project to be buildable in the updated language version. To help transform the rest of your code, you can use Amazon Q chat in the IDE. You can ask Amazon Q to review the partially updated files and provide new code to address issues, such as compilation errors. You can also use features like [Feature development](q-in-IDE-chat.md#develop-code) and [Workspace context](workspace-context.md) to include more of your project as context and get suggestions for multiple files at a time. # Converting embedded SQL in Java applications with Amazon Q Developer The Amazon Q Developer agent for code transformation in the IDE can help you convert embedded SQL to complete Oracle to PostgreSQL database migration with AWS Database Migration Service (AWS DMS). AWS DMS is a cloud service that makes it possible to migrate relational databases, data warehouses, NoSQL databases, and other types of data stores. DMS Schema Conversion in AWS DMS helps you convert database schemas and code objects that you can apply to your target database. For more information, see [What is AWS Database Migration Service?](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html) in the *AWS Database Migration Service User Guide*. When you use AWS DMS and DMS Schema Conversion to migrate a database, you might need to convert the embedded SQL in your application to be compatible with your target database. Rather than converting it manually, you can use Amazon Q in the IDE to automate the conversion. Amazon Q uses metadata from a DMS Schema Conversion to convert embedded SQL in your application to a version that is compatible with your target database. Currently, Amazon Q can convert SQL in Java applications for Oracle databases migrating to PostgreSQL. You will only see the option to transform SQL code in the IDE if your application contains Oracle SQL statements. See the prerequisites for more information. ## Step 1: Prerequisites Before you continue, make sure you’ve completed the steps in [Set up Amazon Q in your IDE](q-in-IDE-setup.md). Before you begin a code transformation job for SQL conversion, make sure the following prerequisites are met: + You are migrating a Java application with embedded SQL from an Oracle database to a PostgreSQL database. Your application must contain Oracle SQL statements for it to be eligible for transformation. + You have completed the process for converting your database schema using AWS DMS Schema Conversion. For more information, see [Migrating Oracle databases to Amazon RDS for PostgreSQL with DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html) in the *Database Migration Guide*. + After schema conversion is complete, you have downloaded the migration project file from the AWS DMS console. ## Step 2: Configure your application To convert your embedded SQL code, your Java project must contain at least one `.java` file. If you are using a JetBrains IDE, you must set the SDK field in Project Structure settings to the applicable JDK. For information on configuring Project Structure settings, see [Project structure settings](https://www.jetbrains.com/help/idea/project-settings-and-structure.html) in the JetBrains documentation. ## Step 3: Convert embedded SQL To convert the embedded SQL code in your Java application to a format that is compatible with your PostgreSQL target database, complete the following steps: 1. In your IDE where Amazon Q is installed, open the Java codebase that contains the embedded SQL you need to convert. 1. Choose the Amazon Q icon to open the chat panel. 1. Ask Amazon Q to transform your application in the chat panel. 1. If your Java application is eligible for SQL conversion, Amazon Q will prompt you to choose which type of transformation you'd like to perform. Enter **SQL conversion**. 1. Amazon Q prompts you to upload the schema metadata file you retrieved from Amazon S3. In the chat, Amazon Q provides instructions for retrieving the file. 1. Amazon Q prompts you to provide the project that contains the embedded SQL as well as the database schema file. Choose the appropriate files from the dropdown menus in the chat panel. 1. Confirm the details Amazon Q retrieved from the database schema are accurate. 1. Amazon Q begins converting your SQL code. This might take a few minutes. 1. After Amazon Q converts the SQL code, it provides a diff with any updates it has made to your files. Review the changes in the diffs, and then accept the changes to update your code. Amazon Q also provides a transformation summary with details about the changes it made. 1. After updating your code, return to the AWS DMS console to verify the new SQL is compatible with the migrated database. # Transforming code on the command line with Amazon Q Developer You can transform your applications from the command line with the Amazon Q Developer command line transformation tool. To transform your code, you provide the path to your source code and any necessary configuration files, and Amazon Q generates new code in a series of steps. Throughout the transformation, Amazon Q builds code on your local environment to verify changes. For more information, see [Building code in your local environment](#local-builds). Amazon Q creates a new branch in your repository where it commits the code changes. When the transformation is complete, you can merge the branch into your original branch to incorporate the changes into your codebase. To get started, install the command line tool and authenticate, and then see the commands to configure and start a transformation. **Topics** + [ ## Building code in your local environment ](#local-builds) + [ ## Commands ](#commands) + [ # Running a transformation on the command line with Amazon Q Developer ](run-CLI-transformations.md) + [ # Troubleshooting transformations on the command line ](troubleshooting-CLI-transformations.md) + [ # Amazon Q Developer command line transformation tool version history ](transform-CLI-versions.md) ## Building code in your local environment During a transformation, Amazon Q performs verification builds in your local environment. Amazon Q transforms your code on the server side in multiple steps. After each step, Amazon Q sends the code to your local environment to build and test the changes it made. The code is then sent back to the server side to continue the transformation. The build in your local environment helps verify the transformed code by allowing Amazon Q to run tests that require access to private resources. To minimize security risks associated with building AI-generated code in your local environment, Amazon Q reviews and updates the code it generates to address security concerns. **Note** Amazon Q performs transformations based on your project's requests, descriptions, and content. To maintain security, avoid including external, unvetted artifacts in your project repository and always validate transformed code for both functionality and security. ## Commands For step-by-step instructions for running these commands, see [Running a transformation on the command line with Amazon Q Developer](run-CLI-transformations.md). To configure a transformation and authenticate to Amazon Q Developer Pro, run: ``` qct configure ``` To start a transformation for a Java upgrade, run the following command. For **, you can enter `JAVA_1.8`, `JAVA_8`, `JAVA_11`, `JAVA_17`, or `JAVA_21`. For **, you can enter either `JAVA_17` or `JAVA_21`. Both `--source_version` and `--target_version` are optional. The `--trust` flag enables a transformation to run while vetting code to maintain security. ``` qct transform --source_folder --source_version --target_version --trust ``` To start a transformation for a SQL conversion, run: ``` qct transform --source_folder --sql_conversion_config_file ``` To see what version of the command line tool for transformation you are using, run: ``` qct -v ``` To get help with transformations, run: ``` qct -h ``` To view your transformation job history, run: ``` qct history ``` For more information about viewing and managing your transformation job history, see [Viewing job history on the command line](transformation-job-history.md#cli-job-history). # Running a transformation on the command line with Amazon Q Developer Complete these steps to transform your code on the command line with the Amazon Q Developer command line tool. ## Prerequisites Before you begin a transformation on the command line, the following prerequisites must be met: + If you're upgrading your Java code version, your project meets the [prerequisites for upgrading Java versions with Amazon Q](code-transformation.md#java-upgrade-prerequisites). + If you're converting embedded SQL in a Java application, your application meets the [prerequisites for converting embedded SQL with Amazon Q](transform-sql.md#sql-transform-prereqs). + You have Python installed on your command line environment. This is how you will install the command line tool. The minimum supported Python version is 3.12. + You are running the transformation on macOS or Linux. + The size of your application is 2 GB or smaller. + If you have specific dependencies you want Amazon Q to upgrade, you have configured a [dependency upgrade file](#step-3-dependency-upgrade-file). ## Step 1: Choose authentication method and add permissions You can authenticate IAM Identity Center to run transformations on the command line. Ensure you have the proper permissions. **Note** Customer managed keys aren't supported for transformations performed on the command line. ### Add permissions The IAM identity associated with the Amazon Q Developer subscription you are using to authenticate must have permissions to perform transformations on the command line. Before you proceed, ensure your IAM identity has the permissions defined in [Allow users to run transformations on the command line](id-based-policy-examples-users.md#id-based-policy-examples-allow-cli-transformations). ### Authenticate with IAM Identity Center through a Amazon Q Developer subscription To authenticate with IAM Identity Center, you must be [subscribed to Amazon Q Developer Pro as a workforce user](subscribe-users.md) by your administrator, and you must provide the Start URL to authenticate through your subscription. You or your administrator can find the Start URL in the Amazon Q Developer console. For more information see, [Finding the Start URL for use with Amazon Q Developer](manage-account-details.md). To add required permissions, see [Add permissions](#transform-CLI-add-permissions). You provide the Start URL in [Step 4: Configure and authenticate](#step-4-configure-auth). ## Step 2: Install the tool 1. [Download the Amazon Q command line tool for transformations](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.2.zip) and unzip it. To download a previous version of the command line tool, see [Version history](transform-CLI-versions.md). 1. We recommend that you set up a virtual environment in Python to install the tool. To create a virtual environment, open a terminal window in the directory where you want to install the tool and run: ``` python -m venv qct-cli ``` 1. To activate the virtual environment, run: ``` source qct-cli/bin/activate ``` 1. To install the tool on your command line, run the following command with the path to where you unzipped the tool, based on your machine architecture: ------ #### [ Linux\$1aarch64 ] ``` pip install /Linux_aarch64/amzn_qct_cli-1.2.2-py3-none-any.whl ``` ------ #### [ Linux\$1x86\$164 ] ``` pip install /Linux_x86_64/amzn_qct_cli-1.2.2-py3-none-any.whl ``` ------ **Note** If you are using an older version of the command line tool for transformations, replace `1.2.2` with the [version](transform-CLI-versions.md) you downloaded. 1. To verify that the tool was installed, run: ``` which qct ``` ## Step 3: Create a dependency upgrade file (optional) You can provide Amazon Q with a *dependency upgrade file*, a YAML file that lists your project's dependencies and which versions to upgrade to during a transformation. By providing a dependency upgrade file, you can specify third and first party dependencies that Amazon Q might not otherwise know to upgrade. First party dependencies refer to the libraries, plugins, and frameworks that your organization maintains and are only available locally or on your organization’s private network. Amazon Q is able to access your first party dependencies when it performs builds in your local environment. For more information, see [Building code in your local environment](transform-CLI.md#local-builds). Third party dependencies are publicly available or open source dependencies that aren’t unique to your organization. You can specify first party dependencies you want to upgrade in a YAML file, and Amazon Q upgrades them during the JDK upgrade (for example, Java 8 to 17). You can initiate a separate transformation (17 to 17 or 21 to 21) after the initial JDK upgrade to upgrade third-party dependencies. Once Amazon Q performs a minimum JDK upgrade, you can initiate a separate transformation to upgrade all third party dependencies. Alternatively, you can specify third party dependencies and their versions in a YAML file to only upgrade those dependencies during the library upgrade transformation. Amazon Q will prompt you to provide a dependency upgrade file during the transformation. If you want to provide one, first make sure you've configured the file properly. The following fields are required in the YAML file: + name - The name of the dependency upgrade file. + description (optional) - A description of the dependency upgrade file, and for which transformation. + dependencyManagement - Contains the list of dependencies and plugins to upgrade. + dependencies - Contains the name and version of the libraries to upgrade. + plugins - Contains the names and versions of the plugins to upgrade. + identifier - The name of the library, plugin, or other dependency. + targetVersion - The version of the dependency to upgrade to. + versionProperty (optional) - The version of the dependency you're defining, as set with the `properties` tag in your application's `pom.xml` file. + originType - Whether the dependency is first or third party, specified by either FIRST\$1PARTY or THIRD\$1PARTY. Following is an example of a dependency upgrade YAML file, and the required configuration for Amazon Q to parse: ``` name: dependency-upgrade description: "Custom dependency version management for Java migration from JDK 8/11/17 to JDK 17/21" dependencyManagement: dependencies: - identifier: "com.example:library1" targetVersion: "2.1.0" versionProperty: "library1.version" # Optional originType: "FIRST_PARTY" - identifier: "com.example:library2" targetVersion: "3.0.0" originType: "THIRD_PARTY" plugins: - identifier: "com.example.plugin" targetVersion: "1.2.0" versionProperty: "plugin.version" # Optional originType: "THIRD_PARTY" ``` ## Step 4: Configure and authenticate Before you can begin a transformation, you must authenticate with IAM Identity Center and provide configuration details for your transformation. 1. To start the transformation configuration process, run the following command: ``` qct configure ``` 1. You are prompted to enter a JDK path for each supported Java version. You only need to specify the path to the JDK of the source version of your Java application, not the target version. 1. Next, to authenticate with IAM Identity Center, you are prompted to enter the start URL for your Amazon Q Developer Pro subscription profile. Then, enter the AWS Region where you were subscribed in the following format: `us-east-1`. For a list of supported Regions, see [Supported Regions](regions.md). For a list of Region codes, see [Regional endpoints ](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the *AWS General Reference guide*. 1. Your configuration preferences are saved to a configuration.ini file. ## Step 5: Run a transformation Choose the type of transformation you're performing to see the required configuration and commands. **Note** Do not turn off or close your local machine during the code transformation because client-side build requires a stable network connection. ------ #### [ Java upgrade ] **Modifying the transformation plan** During Java version upgrades, Amazon Q generates a transformation plan that you can review before the transformation begins. You have the option to request the following changes to the plan: + Which libraries Amazon Q upgrades, from the list included in the plan + Example prompts: + Only upgrade , , and + Don't upgrade or + The target version to upgrade a library to + Example prompts: + Upgrade to this version instead + Which steps Amazon Q should perform + Example prompts: + Only complete steps 1-7 + Don't run steps 5-9 + Add additional dependencies to upgrade (only an option when upgrading to a newer JDK version) + Example prompts: + Also upgrade to **Upgrade Java code** 1. Run the following command to start a transformation for a Java upgrade. Replace `` with the path to the folder with the code you're transforming and `` with either `JAVA_17` or `JAVA_21`. ``` qct transform --source_folder --target_version ``` Additional command options: + If you are specifying dependencies to upgrade, add the `--dependency_upgrade_file` option with the path to your dependency upgrade file. + If you don’t want to review or update the transformation plan, add the `--no-interactive` flag to your command. Amazon Q won’t ask you for feedback on the plan, and you won’t have the opportunity to request changes. 1. Your Maven version is verified before the transformation begins. If you have at least the minimum supported version, you will see the following output: ``` Running command: mvn --version at: path/to/current/directory Your Maven version is supported for transformations. ``` If you don’t have a supported version of Maven, you must update it to continue. For more information, see the [Prerequisites](#CLI-transformation-prerequisites). 1. If you didn’t add the `--no-interactive` flag, Amazon Q will prompt you to provide feedback on the transformation plan. You can explain the changes you want to make in English natural language, and Amazon Q will update the plan if it can support the changes you request. 1. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted. Your upgraded code will be committed to the new branch Amazon Q created. Amazon Q will commit the code in one or multiple commits, depending on the selection you made when you ran `qct configure`. 1. If you're running another transformation after upgrading your Java version, start the second transformation in the same branch where you committed the changes from the first transformation. ------ #### [ SQL conversion ] Before you begin, make you sure you've read [Converting embedded SQL in Java applications with Amazon Q Developer](transform-sql.md) to understand the prerequisites for this type of transformation. 1. To convert embedded SQL, you must first create a YAML file that contains the path to the schema metadata file from your [AWS DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html). Following is the required format of the file: ``` schema_conv_metadata_path: ``` 1. Run the following command to start a transformation for a SQL conversion. Replace `` with the path to the folder with the code you're transforming and `` with the path to the YAML file you created in step 1. ``` qct transform --source_folder --sql_conversion_config_file ``` 1. If Amazon Q finds multiple schemas in your schema metadata file, it will stop the transformation and provide a list of the detected schemas. Choose which schema to use for the SQL conversion, and then add a new field `schema: ` to the YAML file. 1. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted. Your upgraded code will be committed to the new branch Amazon Q created. ------ ## Pause or cancel a transformation You can choose to pause or cancel your current transformation job. You can pause a transformation job for up to 12 hours before you can resume again. **To pause or cancel a code transformation job** 1. In your CLI terminal, press **Ctrl\$1C** on your keyboard. 1. Select whether you want to pause or cancel your tranformation. + Enter `1` if you want to puase the code transformation job. You can resume the job within 12 hours to continue the code transformation using the following QCT command: ``qct transform --source_folder=≤/Path/Given/Originally/To/QCT>``. + Enter `2` if you want to cancel the code tranformation job. # Troubleshooting transformations on the command line The following information can help you troubleshoot common issues when transforming applications on the command line with Amazon Q Developer. ## Why is my bearer token not refreshing? If you see the following error, it means you need to refresh the bearer token used for authentication. ``` Refreshing bearer token ('Error refreshing bearer token due to: ', InvalidGrantException('An error occurred (InvalidGrantException) when calling the CreateToken operation: ')) ('Error getting bearer token due to: ', RuntimeError(('Error refreshing bearer token due to: ', InvalidGrantException('An error occurred (InvalidGrantException) when calling the CreateToken operation: ')))) ``` To address this error, run the following command: ``` rm ~/.aws/qcodetransform/credentials.json ``` Once you remove the outdated credentials file, run `qct transform` again to restart the transformation. ## Why isn't the most recent version of the command line tool being used? When you download a new version of the command line tool for transformations, sometimes a previous version of the tool still gets used. To make you're using the most recent version of the tool, download the [most recent version](transform-CLI-versions.md). Then run the following command with the path to where you unzipped the tool, based on your machine architecture: ------ #### [ Linux\$1aarch64 ] ``` pip install /Linux_aarch64/amzn_qct_cli-1.2.2-py3-none-any.whl --force-reinstall ``` ------ #### [ Linux\$1x86\$164 ] ``` pip install /Linux_x86_64/amzn_qct_cli-1.2.2-py3-none-any.whl --force-reinstall ``` ------ **Note** If you're using an older version of the command line tool for transformations, replace `1.2.2` with the [version](transform-CLI-versions.md) you downloaded. # Amazon Q Developer command line transformation tool version history Review the following information for details about current and past releases of the Amazon Q Developer command line transformation tool. The table includes the download link, release date, and release notes for each version. **** | Version | Release date | Release notes | | --- | --- | --- | | [1.2.2 (latest)](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.2.zip) | February 26, 2026 | Added promotional banner for AWS Transform custom to QCT CLI. Banner display on transform command execution and help text. New --skip-banner flag to suppress banner output. | | [1.2.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.1.zip) | September 9, 2025 | Updated Maven extension to include first-party parent POMs during initial project upload | | [1.2.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.0.zip) | August 7, 2025 | Added support for viewing job history and for module structure visualization for Maven Java projects. | | [1.1.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.1.0.zip) | July 21, 2025 | Includes support for collecting telemetry about transformations. | | [1.0.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.0.0.zip) | June 27, 2025 | The command line transformation tool is generally available and supports authentication through AWS IAM Identity Center with a Amazon Q Developer Pro subscription only. Added support for subscriptions in the Europe (Frankfurt) Region. | | [0.6.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.6.0.zip) | June 6, 2025 | Includes support for providing a dependency upgrade file and iterating on the transformation plan. | | [0.5.2](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.2.zip) | April 16, 2025 | Bug fixes to resolve issues when resuming jobs and failures for applications with first-party dependencies. | | [0.5.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.1.zip) | March 13, 2025 | When you authenticate with IAM, you no longer need to provide an AWS Region. Also includes bug fix to include job status in output logs. | | [0.5.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.0.zip) | February 28, 2025 | Includes support for authenticating with IAM through the AWS CLI. | | [0.4.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.4.1.zip) | February 17, 2025 | Bug fix to include support for entering the AWS Region where your Amazon Q Developer subscription is configured. | | [0.4.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.4.0.zip) | February 14, 2025 | Includes support for upgrading Java applications to Java 21. | | [0.3.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.3.0.zip) | February 12, 2025 | Includes support for converting embedded SQL in Java applications. | | [0.2.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.2.0.zip) | February 3, 2025 | Includes support for receiving upgraded Java code in multiple commits. | | [0.1.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.1.0.zip) | November 27, 2024 | Initial release. Includes support for upgrading Java code versions from the command line. | # Viewing transformation job history Amazon Q provides a comprehensive overview of your Java transformation job history, allowing you to track and review your transformation jobs in both IDEs and the command line. Transformation job history includes the following information about a job: + **Date** – When the transformation job was executed + **Project name** – The name of the project that was transformed + **Status** – The current status of the transformation job + **Duration** – How long the transformation took to complete + **Job ID** – A unique identifier for the transformation job + **Diff patch** – A link or path to the final diff patch file showing all code changes + **Summary** – A link or path to the transformation summary file with details about the changes made **Note** Only transformations run since this feature was released will be available in the job history. For the feature release date, see [Document history for Amazon Q Developer User Guide](doc-history.md). ## Viewing job history in IDEs **Note** This feature is currently available in Visual Studio Code only. The Transformation Hub in Visual Studio Code provides a comprehensive view of your Java transformation job history. A table in the Transformation Hub lists your 10 most recent transformation jobs from the last 30 days. From the table, you can access transformation artifacts and refresh jobs to track progress and get missing artifacts. ### Retrieve transformation artifacts You can access transformation artifacts, such as the diff patches and summary files, from the job history table. Choose the appropriate links to open the diff or summary in your IDE. Artifacts are stored locally in the `.aws/transform` directory, so you can also access previously downloaded transformation artifacts from past jobs. ### Refresh job status You can refresh the job status from the job history table. Refresh a failed job to get an updated status from the server side that may not have reached your server yet, such as when Amazon Q is able to resume a failed job. You can also refresh completed jobs to download artifacts that may not have appeared yet. ### How job history is stored for jobs run in the IDE For Visual Studio Code, all transformation job information and artifacts are stored locally in the `.aws/transform` directory. The storage is organized as follows: ``` .aws/transform/ ├── [project-name-1]/ │ ├── [job-id-1]/ │ │ ├── diff.patch │ │ ├── [summary-1]/ │ │ │ └── summary.md │ │ │ └── buildCommandOutput.log │ └── [job-id-2]/ │ ├── diff.patch │ ├── [summary-2]/ │ │ └── summary.md │ │ └── buildCommandOutput.log └── [project-name-2]/ └── [job-id-3]/ ├── diff.patch ├── [summary-3]/ │ └── summary.md │ └── buildCommandOutput.log ``` ## Viewing job history on the command line For transformations on the command line, the **qct history** command provides access to your transformation job history with customization options. For the CLI, transformation job history information is stored locally in the `.aws/qcodetransform/history/` directory. ### Using the qct history command The basic command to view your transformation job history is: ``` qct history ``` By default, this command displays the 10 most recent transformation jobs, in addition to any paused or in-progress jobs. You can also specify how many job history entries to display with the **--limit** flag. For example, to show 20 jobs, run: ``` qct history --limit 20 ``` # Troubleshooting issues with Java transformations The following information can help you troubleshoot common issues when transforming Java applications with Amazon Q Developer. **Topics** + [ ## Why can't Amazon Q upload my project? ](#project-upload-fail) + [ ## Why are my Maven commands failing? ](#maven-commands-failing) + [ ## How do I add Maven to my `PATH`? ](#add-maven-to-path) + [ ## Why can't Amazon Q build my code? ](#build-fail) + [ ## Why did my transformation fail after 55 minutes? ](#build-time-limit) + [ ## Why can’t I download my transformed code? ](#download-code-fail) + [ ## How do I access code transformation logs? ](#logs) + [ ## How do I find my transformation job ID? ](#job-id) ## Why can't Amazon Q upload my project? If your project fails to upload, it’s likely due to one of the following issues. See the topic that corresponds to the error you see from Amazon Q. **Topics** + [ ### Reduce project size ](#reduce-project-size) + [ ### Configure proxy settings in your IDE ](#configure-proxy) + [ ### Allow access to Amazon S3 ](#allowlist-s3-bucket) ### Reduce project size To transform your code, Amazon Q generates a project artifact, which includes your source code, project dependencies, and build logs. The maximum project artifact size for a transformation job is 2 GB. If you get an error related to project artifact size, you must decrease the size of your project or try transforming a smaller project. You can view the size of your project artifact file in the code transformation logs. For more information, see [How do I access code transformation logs?](#logs) ### Configure proxy settings in your IDE To transform your code, Amazon Q uploads your project artifact to a service-owned Amazon S3 bucket. Part of the upload process involves using SSL or TLS certificates to establish communication between Amazon S3 and your IDE. If you are using a proxy server, the SSL or TLS certificates used by your proxy server must be trusted, otherwise Amazon Q is not able to upload your project. If you receive an error related to your proxy or certificates, you likely need to configure your IDE or operating system to trust your certificates or update other proxy settings. **Note** You might also encounter issues unrelated to certificates if you are behind your organization’s proxy server or firewall. If you complete the following procedures to configure your certificates and still have issues, contact your network administrator to ensure you are allowed to communicate with Amazon S3 from your IDE. For more information, see [Allow access to Amazon S3](#allowlist-s3-bucket). #### Configure certificates in JetBrains To configure your JetBrains IDE Java Runtime Environment (JRE) to trust the SSL or TLS certificates used by your proxy server, you must import the SSL or TLS certificates to the `cacerts` file in the JRE. The `cacerts` file is a file that contains trusted root certificates for secure connections such as HTTPS and SSL, and it's part of the JRE's security settings. To import a certificate, complete the following procedure. **Note** We recommend making a backup of the `cacerts` file before modifying it, as any mistakes can cause issues with secure connections. 1. Determine the path to the `cacerts` file in your JRE. The path of the `cacerts` file in the internal JRE shipped with your JetBrains IDE depends on the operating system and the version of the JetBrains IDE you’re using. Following are examples of paths to the `cacerts` file in common operating systems. Choose your operating system to see examples. **Note** `` refers to the directory where JetBrains products are installed. This directory is typically chosen during the installation process. The `jbr` folder represents the JRE bundled with JetBrains IDEs, which is a specific version of the JRE tailored for use with JetBrains IDEs. ------ #### [ Windows ] The `cacerts` file path for a JetBrains IDE installed on Windows is: ``` \jbr\bin\cacerts ``` For example, if you installed a JetBrains IDE on Windows in the default location, the path might be: ``` C:\Program Files\JetBrains\jbr\bin\cacerts ``` ------ #### [ macOS ] The `cacerts` file path for a JetBrains IDE installed on macOS is: ``` /Applications/JetBrains Toolbox//JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts ``` For example, if you installed a JetBrains IDE on macOS in the default location, the path might be: ``` /Applications/JetBrains Toolbox/2022.3.4/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts ``` ------ #### [ Linux ] The `cacerts` file path for a JetBrains IDE installed on Linux is: ``` /opt/jetbrains/jbr/lib/security/cacerts ``` ------ 1. Determine the certificate you need to import to the `cacerts` file. The certificate file typically has a `.cer`, `.crt`, or `.der` file extension. If you aren’t sure which certificates you need to add, contact your network administrator. 1. Import the certificate to the `cacerts` keystore. You can do this with the Java `keytool` command. 1. Open a command prompt and enter the following command: ``` keytool -import -alias -file -keystore ``` 1. For ``, you can add a name for the certificate you are importing to refer to it later. This option is optional. 1. For ``, specify the path to the certificate you are importing. This should be a path to the `.cer`, `.crt`, or `.der` file containing the certificate. 1. For ``, specify the path to the `cacerts` keystore file you saved in step 1. This is the file where you are importing the certificate. For example, if you want to import a certificate named `my_certificate.cer` into the `cacerts` keystore of the bundled JRE in IntelliJ IDEA on Windows, and you want to give the alias `myalias` to the certificate, the command might be: ``` keytool -import -alias myalias -file my_certificate.cer -keystore "C:\Program Files\JetBrains\IntelliJ IDEA 2022.3.2\jbr\bin\cacerts" ``` 1. During the import process, you'll be prompted to enter the keystore password. The default password for the `cacerts` keystore is `changeit`. 1. After running the command, you'll be asked to trust the certificate. To confirm the certificate is trusted and complete the import, enter `yes`. 1. You might also need to add the certificates to the IDE itself, in addition to the JRE. For more information, see [Server Certificates](https://www.jetbrains.com/help/idea/settings-tools-server-certificates.html) in the JetBrains documentation. #### Configure certificates in Visual Studio Code To configure Visual Studio Code to trust the SSL or TLS certificates used by your proxy server, make sure you have configured the following proxy settings for your operating system. ##### Configure certificates in Visual Studio Code on macOS Configure the following proxy settings for Visual Studio Code on macOS. ##### Add certificates to your macOS keychain If you haven’t already, you must add the certificates used by your proxy server to your macOS keychain. For information on adding certificates to your keychain, see [Add certificates to a keychain using Keychain Access on Mac](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac) in the Keychain Access User Guide. ##### Install the Mac CA VSCode extension The [Mac CA VSCode extension](https://marketplace.visualstudio.com/items?itemName=linhmtran168.mac-ca-vscode) allows Amazon Q to access the certificates you added to Keychain Access on your Mac. To install the extension: 1. Search for `mac-ca-vscode` in the VS Code extensions pane, and choose **Install**. 1. Restart VS Code. ##### Update proxy settings in VS Code on macOS Update the following settings to make sure VS Code is configured properly for your proxy. 1. Open settings in VS Code. 1. Enter `proxy` in the search bar. 1. In the **Http: Proxy** field, add your proxy URL. 1. Deselect **Http: Proxy Strict SSL**. 1. In the **Http: Proxy Support** dropdown list, choose **on**. 1. In the settings search bar, enter `http.experimental.systemCertificatesV2`. Select **Http › Experimental: System Certificates V2**. ##### Configure certificates in Visual Studio Code on Windows Configure the following proxy settings for Visual Studio Code on Windows. ##### Add certificate as a trusted root certificate on Windows If you haven't already, you must add the certificates used by your proxy server to your Trusted Root Certification Authorities store on Windows. To add a certificate, complete the following procedure: 1. Open the search tool or a Run command window. 1. Enter the following to open the Certificate Manager tool: ``` certmgr.msc ``` 1. Choose the **Trusted Root Certification Authorities** store. 1. Right-click **Certificates**, choose **All Tasks**, and then choose **Import...**. 1. Follow the instructions given to import your proxy certificate. 1. After you've imported your certificate, confirm the certificate was added. In the **Trusted Root Certification Authorities** store, double click **Certificates**. Right-click the certificate you added and choose **Properties**. Under **Certificate purposes**, the option **Enable all purposes for this certificate** should be selected. ##### Install the Win-CA VSCode extension The [Win-CA VSCode extension](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca) allows Amazon Q to access the certificates you added to Trusted Root Certificates in Windows. To install the extension: 1. Search for `win-ca ` in the VS Code settings pane. 1. In the **Inject** dropdown list, choose **append**. ##### Update proxy settings in VS Code on Windows Update the following settings to make sure VS Code is configured properly for your proxy. 1. Open settings in VS Code. 1. Enter `proxy` in the search bar. 1. In the **Http: Proxy** field, add your proxy URL. 1. Deselect **Http: Proxy Strict SSL**. 1. In the **Http: Proxy Support** dropdown list, choose **on**. 1. In the settings search bar, enter `http.experimental.systemCertificatesV2`. Select **Http › Experimental: System Certificates V2**. 1. Restart VS Code. ### Allow access to Amazon S3 During a transformation, Amazon Q uploads your code to a service-owned Amazon S3 bucket. If your network or organization hasn’t configured access to Amazon S3, Amazon Q isn’t able to upload your project. To ensure Amazon Q can upload your project, make sure your proxy configuration and other network components, such as Data Lost Prevention (DLP) policies, are configured to allow access to Amazon S3. You might also need to allowlist the Amazon S3 bucket where Amazon Q uploads your project. For more information, see [Amazon S3 bucket URLs and ARNs to allowlist](firewall.md#data-perimeters). If you transform a large project, DLP policies or other network components might cause delays and prevent a successful upload if they aren’t configured to allowlist the Amazon S3 bucket. If you choose not to allowlist the bucket, you might need to transform a smaller project so that Amazon Q can upload it. ## Why are my Maven commands failing? Following are Maven configuration issues that you might see in the JetBrains and Visual Studio Code IDEs. If you address the issues and still see Maven errors, there might be an issue with your project. Use the information in the error logs to address any issues with your project, and then try transforming your project again. ### Update Maven configuration in JetBrains If a transformation fails in JetBrains due to Maven command issues, the error logs appear on the **Run** tab. Use the information in the logs to address the issue. Following are some issues that you might need to address: + Make sure that your Maven home path is set to **Bundled**. Go to **Settings**, and then expand the **Build, Execution, Deployment** section. Expand the **Build Tools** section and then expand **Maven**. In the **Maven home path** dropdown list, choose **Bundled**. + Make sure that the Java runtime environment (JRE) is using your project JDK. Go to **Settings**, and then expand the **Build, Execution, Deployment** section. Expand **Maven** and choose **Runner**. In the **JRE** dropdown list, choose **Use Project JDK**. + Make sure that Maven is enabled. Go to **Settings** and choose **Plugins**. Search for Maven and choose the Maven plugin. If you see an **Enable** button, choose it to enable Maven. ### Update Maven configuration in Visual Studio Code If a transformation fails in VS Code because of Maven command issues, a text file that contains the error logs opens in a new tab. Use the information in the logs to address the issue. Make sure that you have configured either one of the following options: + Your project contains a Maven wrapper in the project root folder + A version of Maven supported by Amazon Q is available on your `PATH` For more information, see [How do I add Maven to my `PATH`?](#add-maven-to-path) ## How do I add Maven to my `PATH`? To transform your code in VS Code without using a Maven wrapper, you must install Maven and add it to your `PATH` variable. To check if you have Maven installed correctly already, run `mvn -v` in a new OS terminal outside of Visual Studio Code. You should see an output with your Maven version. If you get an output in your Visual Studio Code terminal but not in your OS terminal, or if the command isn't found, you need to add Maven to your `PATH`. To add Maven to your `PATH`, follow the instructions for your machine. ------ #### [ macOS ] To add Maven to your macOS `PATH`, complete the following steps. 1. Locate your Maven installation directory, or the folder where you installed Maven, and save the path to that folder. 1. Open the configuration file for your shell in an editor of your choice. For recent macOS versions, the default shell is `zsh` and the default configuration file is located at `~/.zshrc`. Add the following lines to the bottom of the configuration file. Set the value of `M2_HOME` to the path you saved in step 1: ``` export M2_HOME="your Maven installation directory" export PATH="${M2_HOME}/bin:${PATH}" ``` These commands make the `mvn` command available in all terminals. 1. Close all OS terminal windows and quit all Visual Studio Code instances. 1. To verify that Maven was added to your `PATH`, open a new OS terminal and run the following command: ``` mvn -v ``` You should see an output with your Maven version. 1. After seeing your Maven output, restart Visual Studio Code. You might also need to restart your machine. Open a new Visual Studio Code terminal and run the following command: ``` mvn -v ``` The output should be identical to the output in step 4. If the Visual Studio Code output is different, try the following to make sure your setup is correct: + Check your `PATH` variable in Visual Studio Code. An IDE extension might be altering the `PATH` such that it differs from your local `PATH` variable. Uninstall the extension to remove it from your `PATH`. + Check your default shell in Visual Studio Code. If it's set to something other than `zsh`, repeat these steps for your shell. ------ #### [ Windows ] To add Maven to your Windows `PATH`, complete the following steps: 1. Locate your Maven installation directory, or the folder where you installed Maven, and save the path to that folder. 1. Open the Environment Variables window: 1. Choose the Windows button to open the search bar. 1. Enter `Edit environment variables for your account` and choose it. 1. In the **Environment Variables** window, look for the Path variable. If you have a Path variable already, choose **Edit...** to update it. If you don't see a Path variable, choose **New...** to add one. 1. In the **Edit environment variable** window that appears, double click the existing path to edit it, or choose **New** to add a new path entry. Replace the existing Maven path entry with the path you saved in step 1, or add the path as a new entry. At the end of the path, add `\bin` as a suffix, as in the following example: ``` C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin ``` 1. Choose **OK** to save the path entry, and then choose **OK** again in the **Environment Variables** window. 1. Open a new Command Prompt and run the following command: ``` mvn -v ``` You should see an output with your Maven version. ------ ## Why can't Amazon Q build my code? If the transformation fails when Amazon Q is building your code, your project may not be configured properly for the environment where Amazon Q builds your code. You might need to update your build configuration or code implementation. Review the build log output Amazon Q provides to determine if there are changes you can make to your project. Following are some common issues that might prevent Amazon Q from building your code. ### Remove absolute paths in pom.xml If you have an absolute path in your pom.xml file, Amazon Q won’t be able to find the relevant files, and as a result might not be able to build your code. Following is an example of an absolute path that you could have in your `pom.xml` file: ``` /Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home/lib/tools.jar ``` Instead of using an absolute path, you can create a relative path using a pointer. Following is an example of how you can replace the previous absolute path with a relative path: ``` ${java.home}/../lib/tools.jar ``` ### Remove local or external databases in unit tests Amazon Q runs any unit tests in your project when it builds your code. If a unit test calls a local or external database, Amazon Q won’t have access to the database, causing the build to fail. To prevent the build from failing, you must either remove the database call from the unit test or remove the unit test before submitting the transformation. ## Why did my transformation fail after 55 minutes? If your code transformation job fails after 55 minutes, your code build time likely exceeds the build time limit. There is currently a time limit of 55 minutes for building your code. If your local build time takes 55 minutes or longer, reduce your project’s build time to transform your code. If your local build is faster than the build with Code Transformation, check your project for tasks that might be failing or take a longer time in a different environment. Consider disabling long-running test cases. Also consider using timeouts for attempts to access resources that might not be available from the secure IDE environment or the internet. ## Why can’t I download my transformed code? If you aren’t able to download your code after your transformation is complete, it’s likely due to one of the following issues. See the topic that corresponds to the error you see from Amazon Q. **Topics** + [ ### Reduce project size ](#reduce-project-size-output) + [ ### Download code diff within 30 days ](#download-30-hrs) + [ ### Configure proxy settings in your IDE ](#configure-proxy-download) + [ ### Remove wildcard characters in JetBrains proxy settings ](#remove-wildcard) ### Reduce project size After the transformation is complete, Amazon Q generates an output artifact that contains a diff with your upgraded code and a transformation summary with information about the changes it made. The output artifact must be 1 GB or less in order for the IDE to download it. If the output artifact exceeds the limit, you will not be able to download your upgraded code or transformation summary. Try transforming a smaller project to prevent a large output artifact. If the issue persists, contact Support. For information about contacting Support with Amazon Q, see [Using Amazon Q Developer to chat with Support](support-chat.md). ### Download code diff within 30 days The code diff file with your upgraded code is only available for 30 days after the transformation is complete. If it’s been over 30 days since the transformation completed, restart the transformation to download the diff file. ### Configure proxy settings in your IDE Amazon Q downloads your upgraded code from a service-owned Amazon S3 bucket. Part of the download process involves using SSL or TLS certificates to establish communication between Amazon S3 and your IDE. If you are using a proxy server, the SSL or TLS certificates used by your proxy server must be trusted, otherwise Amazon Q is not able to upload your project. To download your code, you might need to configure your IDE to trust certificates or update other proxy settings. For more information on updating your proxy settings, see [Configure proxy settings in your IDE](#configure-proxy). ### Remove wildcard characters in JetBrains proxy settings If you have configured proxy settings in your JetBrains IDE, you might see the following error when downloading your upgraded code: ``` software.amazon.awssdk.core.exception.SdkClientException: Unable to execute HTTP request: Dangling meta character '*' near index 0 ``` This is likely caused by the presence of a wildcard character (\$1) in the **No proxy for** field of your IDE's proxy settings. The Java SDK used by Amazon Q doesn't support wildcard entries in this field. To download your code, remove any wildcards from the **No proxy for** field, and then restart your IDE. If you need to specify hosts that should bypass the proxy, use a regular expression instead of a wildcard. To update proxy settings in your JetBrains IDE, see [HTTP Proxy](https://www.jetbrains.com/help/idea/settings-http-proxy.html) in the JetBrains documentation. ## How do I access code transformation logs? ### Access logs in JetBrains For information about how to access JetBrains log files, see [Locating IDE log files](https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files) in the JetBrains documentation. To find logs emitted by Amazon Q in JetBrains, search the IDE logs for the following string: ``` software.aws.toolkits.jetbrains.services.codemodernizer ``` Code transformation logs start with the preceding string. Logs generated by Maven are displayed on the **Run** tab and have the preceding string before and after the log entry. ### Access logs in Visual Studio Code To find logs emitted by Amazon Q in VS Code, complete the following steps: 1. Choose **View** in the top navigation bar, and then choose **Command Palette**. 1. Search `Amazon Q: View Logs` in the command palette that appears. 1. The logs open in the IDE. To search the log files for `CodeTransformation`, use `CMD + F` or `Control + F`. Code transformation logs in VS Code are prefixed with `CodeTransformation:`. Following is an example of a log generated in VS Code for a Maven copy dependencies error: ``` 2024-02-12 11:29:16 [ERROR]: CodeTransformation: Error in running Maven copy-dependencies command mvn = /bin/sh: mvn: command not found ``` ## How do I find my transformation job ID? ### Find your job ID in JetBrains To find a transformation job ID in JetBrains, go to the **Transformation details** tab in the **Transformation Hub** and choose the **Show Job Status** (clock) icon. ### Find your job ID in Visual Studio Code To find a transformation job ID in VS Code, go to the **Transformation Hub** and choose the **Show Job Status** (clock) icon.