Using upgrade debug mode to upgrade AWS CLI version 1 to AWS CLI version 2 - AWS Command Line Interface
How it worksLimitationsConfigure upgrade debug mode

Using upgrade debug mode to upgrade AWS CLI version 1 to AWS CLI version 2

We recommend that users of AWS CLI version 1 upgrade to AWS CLI version 2 to access new features and enhanced performance. There are changes in behavior between AWS CLI version 1 and AWS CLI version 2 that might require you to update your scripts or commands to get the same behavior. The upgrade debug mode in AWS CLI version 1 outputs warnings when you use features that have different behavior in AWS CLI version 2. This feature improves the upgrade experience by automatically detecting which of your AWS CLI version 1 commands need to be modified before upgrading to AWS CLI version 2 to prevent unexpected issues.

For more details, see Breaking changes between AWS CLI version 1 and AWS CLI version 2.

When you upgrade from AWS CLI version 1 to version 2, you might encounter Breaking changes between AWS CLI version 1 and AWS CLI version 2 that affect your existing scripts and workflows. The upgrade debug mode helps you identify these issues before you complete the migration.

Upgrade debug mode detects when you use features that have breaking changes in AWS CLI version 2. When you run a command that will break after upgrading, the mode displays a warning with specific steps to fix the issue. This saves you time by automatically finding potential problems instead of manually searching through your code.

How it works

If enabled, the upgrade debug mode detects usage of features that were updated with breaking changes in AWS CLI version 2. If you use a command or feature listed in our Breaking changes between AWS CLI version 1 and AWS CLI version 2 after upgrading to AWS CLI version 2, a warning will be shown in the output. Breaking change detection is based on the command used, the arguments supplied, the execution environment (e.g. environment variables, configuration settings, etc.), and for a few cases, the content or configuration of resources in the AWS account being used.

The following example demonstrates what these warnings look like. This command demonstrates an example warning. All warning text starts with "AWS CLI V2 UPGRADE WARNING," followed by the specific warning message. In this case, a warning is output because the command relies on the AWS CLI to retrieve the contents of the URL and use the contents as the --template-body parameter value, which was a feature removed in AWS CLI version 2.

The following example shows what a warning looks like:

$ aws cloudformation create-stack \
  --stack-name "stack012345" \
  --template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"

AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or 
https://, AWS CLI v2 will not automatically request the content of the URL for 
the parameter, and the `cli_follow_urlparam` option has been removed. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.

The following table of all breaking changes, and how to avoid facing a breaking change in AWS CLI version 2. Remediation actions that resolve the warnings in debug mode are in bold.

Breaking change On v1, migrate to v2 behavior On v2, retain v1 behavior
Environment variable added to set text file encoding Unset the PYTHONUTF8 and PYTHONIOENCODING environment variables. Set the AWS_CLI_FILE_ENCODING environment variable to the encoding specified in v1.
Binary parameters are passed as base64-encoded strings by default Encode the value of the parameter with base64. If the parameter is being loaded from a file, encode the file contents with base64. Set the cli_binary_format setting to raw-in-base64-out.
Improved Amazon S3 handling of file properties and tags for multipart copies N/A. Cannot migrate to version 2 behavior in version 1. Use the --copy-props none parameter.
No automatic retrieval of http:// or https:// URLs for parameters Use curl (or alternative tools) to download the contents of the URLs to a local file. Then, load the file contents to the parameter with file://. Alternatively, configure cli_follow_urlparam to false to specify the raw URL as the paramater value. N/A. Impossible to retain version 1 behavior in version 2.
Pager used for all output by default N/A. Cannot migrate to version 2 behavior in version 1. Set the cli_pager setting or AWS_PAGER variable to an empty string.
Timestamp output values are standardized to ISO 8601 format Set the cli_timestamp_format setting to iso8601. Set the cli_timestamp_format setting to wire.
Improved handling of CloudFormation deployments that result in no changes Use the --no-fail-on-empty-changeset parameter. Use the --fail-on-empty-changeset parameter.
Changed default behavior for Regional Amazon S3 endpoint for us-east-1 Region Set the AWS_ENDPOINT_URL_S3 environment variable or the --endpoint-url command line option to the us-east-1 regional URL. Use the --region aws-global command line option.
ecr get-login removed and replaced with ecr get-login-password (1.17.10 or later) Use ecr get-login removed and replaced with ecr get-login-password and pipe the output into a docker command. N/A. Impossible to retain version 1 behavior in version 2.
AWS CLI version 2 support for plugins is changing N/A. Cannot migrate to version 2 behavior in version 1. Configure the cli_legacy_plugin_path to the [plugins] section of the configuration file. Test plugins in version 2, lock your version 2 version, and test your plugins each time you upgrade.
Hidden alias support removed Switch from using the obsolete hidden alias to Hidden alias support removed that works in all versions. N/A. Impossible to retain version 1 behavior in version 2.
The api_versions configuration file setting is not supported Migrate and test your usage of older API versions to the latest API version, and remove api_versions from your configuration settings. N/A. Impossible to retain version 1 behavior in version 2.
AWS CLI version 2 uses only Signature v4 to authenticate Amazon S3 requests Specify the Signature Version to version 4 (see Specifying the Signature Version in request authentication). N/A. Impossible to retain version 1 behavior in version 2.
AWS CLI version 2 is more consistent with paging parameters Move the pagination parameters in the input JSON parameter to the command itself. Remove the pagination parameters from the input JSON parameter.
AWS CLI version 2 provides more consistent return codes across all commands N/A. Cannot migrate to version 2 behavior in version 1. N/A. Impossible to retain version 1 behavior in version 2.

Limitations

We strongly recommend customers review our Breaking changes between AWS CLI version 1 and AWS CLI version 2.

Unsupported Breaking Change Detection

The upgrade debug mode feature supports every breaking change except that AWS CLI version 2 provides more consistent return codes across all commands. This mode cannot account for how you use the error codes returned by the AWS CLI downstream.

Conditional Breaking Change Detection

Detection of Timestamp output values are standardized to ISO 8601 format is the only case where detection depends on the state of the AWS account, and may be subject to breaking changes if the account resources are updated later. If no timestamps are included in the API response from the service, no detections will be made for this breaking change.

If you rely on the timestamp format returned by AWS CLI commands and have not already configured the AWS CLI to use ISO 8601, take extra precaution to ensure your processing of the timestamp will not break after upgrading to version 2.

Unresolvable Breaking Change Detection

Some warnings output by upgrade debug mode cannot be resolved by modifying the command or environment. The following cases are cases where warnings would always be output by upgrade debug mode as long as you use the corresponding feature:

False detections

Warnings output by the upgrade debug mode do not guarantee that breaking changes will be faced after upgrading to AWS CLI v2. Below are cases where warnings would be output by upgrade debug mode, despite there being no breaking change introduced in AWS CLI v2:

Configure upgrade debug mode

You can enable or disable upgrade debug mode using the following methods, listed in order of precedence:

  • Command line options enable or disable upgrade debug mode for a single command. Use --v2-debug to use upgrade debug mode.

  • Environment variables use the AWS_CLI_UPGRADE_DEBUG_MODE variable.