Troubleshooting
This section provides guidance for troubleshooting common issues with AWS Transform custom.
Log Locations
AWS Transform CLI maintains logs in the following locations:
Conversation logs:
These logs contain the full conversation history for debugging specific transformation executions.
Subagent logs:
These logs contain output from subagents that the main agent spawns during transformations. You do not need to manage subagents directly.
Developer debug logs:
These logs provide detailed information about CLI operations and errors. Each log file has a 5MB limit before it rolls over. There may be multiple debug logs in this directory, such as debug1.log and debug2.log.
Common Issues
Installation issues:
If installation fails, ensure you have Node.js 22 or later installed:
node --version
Download Node.js from https://nodejs.org/en/download if needed.
Authentication issues:
Verify your AWS credentials are configured correctly:
aws sts get-caller-identity
Ensure your IAM user or role has the required transform-custom:* permissions.
Network connectivity issues:
If you encounter connection errors, verify network access to required endpoints:
transform-cli.awsstatic.comtransform-custom.<region>.api.aws*.s3.amazonaws.com
If working in an internet-restricted environment, update firewall rules to allowlist these URLs.
Region configuration issues:
If you encounter region-related errors:
Verify your region is supported
Check for environment variables that may override your configuration:
echo $AWS_REGION $AWS_DEFAULT_REGIONCheck your region configuration:
aws configure get regionUpdate your region if needed:
aws configure set region <your-region>Check debug logs for region resolution details
Git issues:
Ensure Git is installed and your repository is under git source control:
git --version git status
AWS Transform custom requires repositories to be under git source control.
Transformation execution issues:
If a transformation fails:
Review the conversation logs at
~/.aws/atx/custom/<conversation_id>/logs/Check for build or test failures in the transformation output
Verify the build command is correct for your project
Try running the transformation in interactive mode to provide feedback
Conversation resumption issues:
If you cannot resume a conversation:
Verify the conversation is less than 30 days old
Check the conversation ID is correct
Ensure you have network connectivity
Continuing a transformation campaign using the CLI
If you started a transformation in the AWS Transform web application, AWS Transform created a campaign for it. You can continue to run and track that campaign using the AWS Transform command line interface (CLI). Use the following procedure when you want to transform more repositories in an existing campaign, or check the progress of its repositories, without using the web application. For AWS managed transformations (transformation names that start with AWS/) in non-interactive mode, you need to provide additionalPlanContext in the --configuration option to specify the target of the transformation, such as the target language version.
Before you begin, your AWS credentials need to be for the same AWS account where you created the campaign, and you need to set the same AWS Region. In the following example, replace aa-example-1 with the Region where you created the campaign.
export AWS_REGION=aa-example-1
To continue a campaign using the CLI
-
Run the following command to list the campaigns in your account, and then find the campaign that you want to continue. The campaign name is the job ID of the transformation that you started in the web application.
atx custom campaign listTo also view the description of each campaign, add
--jsonto the command. -
(Optional) Run the following commands to view the campaign details and the repositories that are already in the campaign. Replace
campaign-namewith the name of your campaign.atx custom campaign get --namecampaign-nameatx custom campaign list-repos --namecampaign-name -
Run the following command to transform a repository and record the result in the campaign.
atx custom def exec \ --code-repository-pathpath-to-repo\ --non-interactive \ --trust-all-tools \ --campaigncampaign-name\ --repo-namerepo-name\ --add-repo \ --configuration "additionalPlanContext=target-details"Replace the following values:
path-to-repo– The local path to the code repository that you want to transform.campaign-name– The name of the campaign that you want to continue.repo-name– The name of the repository in the campaign. The--add-repooption adds the repository to the campaign if it isn't already in the campaign.target-details– The target of the transformation, for exampleThe target Java version to upgrade to is Java 21.
To run the transformation interactively instead, omit
--non-interactiveand--trust-all-tools. If the command returns an error, review the error message, verify the--configurationvalue and the repository path, and then run the command again. For common errors, see the troubleshooting list that follows this procedure. -
Run the following command to track the progress of the repositories in the campaign. A repository shows
TRANSFORMINGwhile the transformation runs andVALIDATEDafter it completes.atx custom campaign list-repos --namecampaign-name
When the transformation completes successfully, the repository shows VALIDATED in the campaign.
You can also manage campaigns using the following commands:
To add repositories to a campaign without running a transformation, run
atx custom campaign add-repos --name.campaign-name--reposrepo-a,repo-bTo create a new campaign, run
atx custom campaign create --name.campaign-name--transformation-nametransformation-name--description "description"To close a campaign when you finish, run
atx custom campaign update-status --name.campaign-name--status CLOSED
If you encounter the following errors while you work with campaigns, use these solutions:
Campaign '
campaign-name' not found. – This error usually occurs when the CLI uses credentials or a Region that differ from the ones that you used to create the campaign. Campaigns are stored per AWS account and Region. Verify that your credentials and theAWS_REGIONvalue match the account and Region where you created the campaign.Could not resolve the AWS Transform endpoint – This error occurs when the value of
AWS_REGIONis a Region that AWS Transform custom doesn't support. SetAWS_REGIONto the Region where you created the campaign.Running this transformation in non-interactive mode requires the --configuration (or -g) input provided with the "additionalPlanContext" section populated. – This error occurs when you run an AWS managed transformation in non-interactive mode without a target. Add
--configuration "additionalPlanContext=to the command, or run the command withouttarget-details"--non-interactive.No repositories found for this campaign. – This message appears when the transformation command stopped before it added the repository to the campaign. Review the error message that the transformation command returned, fix the issue, and then run the command again with
--add-repo.
Getting Support
For additional assistance, visit AWS Support through the AWS Console
When opening a support ticket, include:
Conversation logs from
~/.aws/atx/custom/<conversation_id>/logs/Subagent logs from
~/.aws/atx/custom/<conversation_id>/logs/subagents/Debug logs from
~/.aws/atx/logs/Steps to reproduce the issue
AWS Transform CLI version (
atx --version)
S3 access issues
The AWS Transform custom service vends S3 pre-signed URLs to facilitate uploading and downloading the potentially large transformation files to/from client machines. This means that not only does the CLI interact with the AWS Transform service endpoints but it also interacts with the S3 service endpoints. These interactions use pre-signed URLs so your client's IAM credentials do not require any S3 permissions but sometimes your local machine's proxy server configurations and your network's S3 VPC Endpoint Policies can restrict this traffic.
Please examine the Log Locations for more detailed error messages to help root cause any tool failures or S3 access denied relating to downloading and uploading transformation files.
If you are using a VPN/Proxy server that leverages the https_proxy and no_proxy environment variables, consider adding the following values to your no_proxy environment variable value to bypass the proxy for the S3 and AWS Transform custom service endpoints, for example:
If you are using an AWS PrivateLink for Amazon S3 in your VPC,
this may have a policy defined to restrict S3 traffic. Please ensure your S3 VPC endpoint policy allows GetObject and PutObject operations for the AWS Transform
custom service-owned buckets. This can be accomplished by adding the following statement to your VPC endpoint policy:
{ "Effect": "Allow", "Principal": "*", "Action": ["s3:PutObject","s3:GetObject"], "Resource": "arn:aws:s3:::aws-transform-custom-*/*" }
Explicit Deny statements in policies take precedence over
Allow statements. Review S3 VPC Endpoint policies for
Deny statements that may be restricting access.