Troubleshooting errors for the AWS CLI

Example error text:

$ aws s3 copy
usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help
aws: error: argument subcommand: Invalid choice, valid choices are:

ls                                       | website                                 
cp                                       | mv                                      
....

Various errors can occur if your command is formatted incorrectly or you are using an earlier version from before the feature was released. For more information on resolving errors around these two issues, see Check your AWS CLI command formatting and Confirm that you're running a recent version of the AWS CLI.

Back to top

Example error text:

$ aws --version
command not found: aws

If the aws command cannot be found after first installing or updating the AWS CLI, you might need to restart your terminal for it to recognize any PATH updates.

Back to top

Example error text:

$ aws --version
command not found: aws

If the aws command cannot be found after first installing or updating the AWS CLI, it might not have been fully installed. Try reinstalling by following the steps for your platform in Installing or updating to the latest version of the AWS CLI.

Back to top

If the aws command cannot be found after first installing or updating the AWS CLI on Linux, it might not have execute permissions for the folder it installed in. Run the following command with the PATH to your AWS CLI installation,to provide chmod permissions to the AWS CLI:

$ sudo chmod -R 755 /usr/local/aws-cli/

Back to top

Example error text:

$ aws --version
command not found: aws

You might need to add the aws executable to your operating system's PATH environment variable. To add the AWS CLI to your PATH, use the following instructions for your operating system.

If the aws command shows the wrong version, you might need to restart your terminal for it to recognize any PATH updates. All open terminals needs to be closed, not just your active terminal.

Back to top

If the aws command shows the wrong version and restarting the terminal didn't work, you might need to restart your system for it to recognize your PATH updates.

Back to top

If you updated the AWS CLI and used a different install method than your pre-existing installation, it might cause multiple versions to be installed. For example, if on Linux or macOS you used pip for your current install, but tried to update using the .pkg install file, this could cause some conflicts especially with your PATH pointing to the old version.

To resolve this, uninstall all versions of the AWS CLI and perform a clean install.

After uninstalling all versions, follow instructions appropriate for your operating system to install your desired version of the AWS CLI version 1 or AWS CLI version 2.

Back to top

If the aws --version command still works, you might need to restart your terminal for it to recognize any terminal updates.

Back to top

The AWS CLI might not uninstall correctly if you uninstalled the AWS CLI using a different method than you used to install it, or if you installed multiple versions. For example, if you used pip for your current install, you must use pip to uninstall it. To resolve this, uninstall AWS CLI using the same method that you used to install it.

Back to top

Since the AWS CLI is built using Python, the AWS CLI uses the Python argparse library, including the allow_abbrev argument. Abbreviations of parameters are recognized by the AWS CLI and processed.

The following create-change-set command example changes the CloudFormation stack name. The parameter --change-set-n is recognized as an abbreviation of --change-set-name, and the AWS CLI processes the command.

$ aws cloudformation create-change-set --stack-name my-stack --change-set-n my-change-set

When your abbreviation could be multiple commands, the parameter will not be recognized as an abbreviation.

The following create-change-set command example changes the CloudFormation stack name. The parameter --change-set- is not recognized as an abbreviation, as there are there are multiple parameters it could be an abbreviation of, such as --change-set-name and --change-set-type. Therefore the AWS CLI does not process the command.

$ aws cloudformation create-change-set --stack-name my-stack --change-set- my-change-set

$ aws ec2 describe-vpc-peering-connections \
    --filters Name=tag:TagName,Values=VpcPeeringConnection \
    --filter Name=status-code,Values=active 

Back to top

On Linux or macOS, make sure that the aws program has run permissions for the calling user. Typically, the permissions are set to 755.

To add run permission for your user, run the following command, substituting ~/.local/bin/aws with the path to the program on your computer.

$ chmod +x ~/.local/bin/aws

Back to top

Example error text:

$ aws s3 ls
An error occurred (AcessDenied) when calling the ListBuckets operation: Access denied.

When you run a AWS CLI command, AWS operations are performed on your behalf, using credentials that associate you with an IAM account or role. The policies attached must grant you permission to call the API actions that correspond to the commands that you run with the AWS CLI.

Most commands call a single action with a name that matches the command name. However, custom commands like aws s3 sync call multiple APIs. You can see which APIs a command calls by using the --debug option.

If you are sure that the user or role has the proper permissions assigned by policy, make sure that your AWS CLI command is using the credentials you expect. See the next section about credentials to verify that the credentials the AWS CLI is using are the ones that you expect.

For information about assigning IAM permissions, see Overview of Access Management: Permissions and Policies in the IAM User Guide.

Back to top

The AWS CLI might be reading credentials from a different location than you expect, or your key pair information is incorrect. You can run aws configure list to confirm which credentials are used.

The following example shows how to check the credentials used for the default profile.

$ aws configure list
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                <not set>             None    None
access_key     ****************XYVA shared-credentials-file
secret_key     ****************ZAGY shared-credentials-file
    region                us-west-2      config-file    ~/.aws/config

The following example shows how to check the credentials of a named profile.

$ aws configure list --profile saanvi
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                    saanvi           manual    --profile
access_key         **************** shared-credentials-file
secret_key         **************** shared-credentials-file
    region                us-west-2      config-file    ~/.aws/config

To confirm your key pair details, check your config and credentials files. For more information on config and credentials files, see Configuration and credential file settings in the AWS CLI. For more information on credentials and authentication, including credentials precedence, see Authentication and access credentials for the AWS CLI.

Back to top

If you are using valid credentials, your clock might be out of sync. On Linux or macOS, run date to check the time.

$ date

If your system clock is not correct within a few minutes, use ntpd to sync it.

$ sudo service ntpd stop
$ sudo ntpdate time.nist.gov
$ sudo service ntpd start
$ ntpstat

On Windows, use the date and time options in the Control Panel to configure your system clock.

Back to top

To help protect against replay attacks, the current time can be used during the encryption/decryption process. If the time of the client and server disagree by more than the allowed amount, the process can fail and the request is rejected. This can also happen when you run a command in a virtual machine whose clock is out of sync with the host machine's clock. One possible cause is when the virtual machine hibernates and takes some time after waking up to sync the clock with the host machine.

On Linux or macOS, run date to check the time.

$ date

If your system clock is not correct within a few minutes, use ntpd to sync it.

$ sudo service ntpd stop
$ sudo ntpdate time.nist.gov
$ sudo service ntpd start
$ ntpstat

On Windows, use the date and time options in the Control Panel to configure your system clock.

Back to top

If your AWS keys include certain special characters, such as -, +, /, or %, some operating system variants process the string improperly and cause the key string to be interpreted incorrectly.

If you process your keys using other tools or scripts, such as tools that build the credentials file on a new instance as part of its creation, those tools and scripts might have their own handling of special characters that causes them to be transformed into something that AWS no longer recognizes.

We suggest regenerating the secret key to get one that does not include the special character causing issues.

Back to top

Example error text:

$ aws s3 ls
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

When you use a AWS CLI command, you receive an [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed error message. This is caused by the AWS CLI not trusting your proxy's certificate due to factors such as your proxy's certificate being self-signed, with your company set as the Certification Authority (CA). This prevents the AWS CLI from finding your companies CA root certificate in the local CA registry.

To fix this, instruct the AWS CLI where to find your companies .pem file using the ca_bundle configuration file setting, --ca-bundle command line option, or the AWS_CA_BUNDLE environment variable.

Back to top

Example error text:

$ aws s3 ls
SSL validation failed for regionname [Errno 2] No such file or directory

This is caused by your Certification Authority (CA) bundle file location being configured incorrectly in the AWS CLI. To fix this, confirm where your companies .pem file is located and update the AWS CLI configuration by using the ca_bundle configuration file setting, --ca-bundle command line option, or the AWS_CA_BUNDLE environment variable.

Back to top

Example error text:

$ aws s3 ls
[SSL: CERTIFICATE_ VERIFY_FAILED] certificate verify failed

Errors or unexpected results might occur if an AWS service isn't available for your specified AWS Region or your resources are located in a different AWS Region. For troubleshooting steps, see Check the AWS Region your AWS CLI command is using.

Back to top

Example error text:

$ aws s3 ls
[SSL: UNSAFE_LEGACY_RENEGOTIATION_DISABLED] unsafe legacy renegotiation disabled

The AWS service is using a version of TLS that is incompatible with your device's TLS version. To resolve this issue, update to a supported TLS version. For more information, see Enforcing a minimum version of TLS for the AWS CLI.

Back to top

Confirm you have valid JSON entered for your command. We suggest using a JSON validator for JSON you're having issues formatting.

For more advanced JSON usage in the command line, consider using a command line JSON processor, like jq, to create JSON strings. For more information on jq, see the jq repository on GitHub.

Back to top

Before the AWS CLI receives anything from a command, your terminal processes the command using it's own quoting and escaping rules. Due to a terminal's formatting rules, some of your JSON content may be stripped before the command is passed to the AWS CLI. When formulating commands, be sure to use your terminal's quoting rules.

To troubleshoot, use the echo command to see how the shell is handling your parameters:

$ echo {"ReadCapacityUnits":15,"WriteCapacityUnits":10}
ReadCapacityUnits:15 WriteCapacityUnits:10

$ echo '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}'
{"ReadCapacityUnits":15,"WriteCapacityUnits":10}

Modify your command until your until valid JSON is returned.

For more in-depth troubleshooting, use the --debug parameter to view the debug logs as they'll display exactly what got passed to the AWS CLI:

$ aws dynamodb update-table \
    --provisioned-throughput '{"ReadCapacityUnits":15,WriteCapacityUnits":10}' \
    --table-name MyDDBTable \
    --debug
2022-07-19 22:25:07,741 - MainThread - awscli.clidriver - DEBUG - CLI version: aws-cli/1.18.147 
Python/2.7.18 Linux/5.4.196-119.356.amzn2int.x86_64 botocore/1.18.6
2022-07-19 22:25:07,741 - MainThread - awscli.clidriver - DEBUG - Arguments entered to CLI: 
['dynamodb', 'update-table', '--provisioned-throughput', '{"ReadCapacityUnits":15,WriteCapacityUnits":10}',
 '--table-name', 'MyDDBTable', '--debug']

Use your terminal's quoting rules to fix any issues your JSON input has when being sent to the AWS CLI. For more information on quoting rules, see Using quotation marks and literals with strings in the AWS CLI.

Back to top