Troubleshoot common Cloud Assistant CLI errors - Alibaba Cloud CLI

This topic describes common errors that occur when you use Cloud Assistant CLI and provides troubleshooting solutions.

General troubleshooting methods

If you encounter an issue or receive an error message when you use Cloud Assistant CLI, perform the following checks first to troubleshoot the problem.

Check the network status

Network connectivity issues between the client and the server can prevent requests from reaching the server. Check your network status to ensure that you can access Alibaba Cloud APIs.

Check for missing options

Some commands have required options. The command fails to run if you do not include a required option or if you pass an invalid value for an option. You can view command or API details in the following ways:

When you configure credentials, see Configure credentials and Manage multiple credential configurations to check whether the required options for the configuration command are included.
When you call an OpenAPI, view the required options in the API documentation.
When you use the --force option to call an API, you must also use the --version option to specify the OpenAPI version.

Check the command and parameter format

If Cloud Assistant CLI reports that a command does not exist or a parameter is not recognized, the command or parameter format may be incorrect. Check your command in the following ways:

See Command structure and the corresponding OpenAPI documentation to check the command for spelling or format errors.
Check whether the passed parameters are correct.
Check whether the passed parameters contain special characters that require processing. For more information, see Parameter format.

Check the region and endpoint

An error may occur if an Alibaba Cloud service does not support calls from your specified endpoint or region, or if the resource you want to access is in another region. Cloud Assistant CLI prioritizes endpoints and regions in the following order:

The endpoint specified by the --endpoint option.
The region ID specified by the --region option.
The region ID saved in the credential configuration profile.
The region ID saved in the ALIBABA_CLOUD_REGION_ID environment variable.

Check the request details

If a command returns an unexpected result, you can check whether the request parameters are structured correctly using the following methods.

Use the dry run feature to view request details

Use the --dryrun option to perform a dry run. This operation does not affect your cloud resources. The dry run feature displays information such as identity credentials, the region, and the API version. For more information, see Dry run feature.

Enable and check Cloud Assistant CLI logs

After you enable the log output feature, Cloud Assistant CLI outputs more detailed call information when you run a command. For more information, see Dry run feature.

Confirm credential validity

If you do not configure your identity credentials correctly, various errors may occur when you make calls. Check the following items to ensure that your identity credentials are valid:

Check the current configuration

If you use an unexpected credential configuration to make a call, the command result may be unexpected. Cloud Assistant CLI prioritizes credential configurations in the following order:

The configuration specified by the --profile option.
The configuration specified by the ALIBABA_CLOUD_PROFILE environment variable.
The current configuration specified by the aliyun configure switch command. For more information, see Set the current credential configuration.

Check the credential information saved in the configuration

If the credential information saved in the configuration is incorrect, Cloud Assistant CLI cannot use this configuration to call an OpenAPI. You can check the credential information using the following methods:

Run the aliyun configure list command to view summary information for all credential configurations.
Run the aliyun configure get command to view detailed information of a single credential configuration.

If the credential information is incorrect, reconfigure the identity credentials or run the aliyun configure set command to modify the saved credential information. For more information, see Modify a specified identity credential configuration.

Check the credential mode

When you use credential modes such as RamRoleArn and EcsRamRole, check whether the credential provider works as expected. If Cloud Assistant CLI cannot obtain valid identity credentials, API calls fail.

RamRoleArn, ChainableRamRoleArn: To use this credential mode, ensure that the management permissions of Security Token Service (STS) (AliyunSTSAssumeRoleAccess) are granted to the Resource Access Management (RAM) user or RAM role. For more information, see AssumeRole - Obtain temporary identity credentials of a RAM role.
EcsRamRole: To use this credential mode, see Permission examples to grant the required permissions to the current user identity.
External, CredentialsURI: To use this credential mode, check whether the external program command can obtain credentials.

Check if the identity corresponding to the credentials has access permissions

If your credential information is correct, your current identity may not have the permissions required to perform the current operation. Grant the required permissions to your current identity and try running the command again.

Update or reinstall Cloud Assistant CLI

Cloud Assistant CLI updates often introduce support for new Alibaba Cloud services, features, and parameters. This new functionality is available only in versions of Cloud Assistant CLI released after the functionality is introduced. If you have confirmed that the command and parameter formats are correct, but Cloud Assistant CLI still reports that the command does not exist or a parameter is not recognized, reinstall or update Cloud Assistant CLI to the latest version.

FAQ

The aliyun command is not found

The terminal was not restarted after installation

After you modify the PATH environment variable, you must restart the terminal session for the changes to take effect. Restart all terminal sessions to resolve this issue.

The PATH environment variable is not updated or an incorrect installation path is configured

Run the following command to view the current PATH environment variable and check whether it contains the correct installation directory path.

Linux/macOS

echo $PATH

Windows PowerShell

echo $Env:PATH

Windows command prompt (CMD)

echo %PATH%

The executable file is missing

Check whether the executable file is in the Cloud Assistant CLI installation directory. If the file was deleted or moved to another directory, Cloud Assistant CLI cannot run. You may need to reinstall Cloud Assistant CLI.

Executable file in Windows: aliyun.exe

Executable file in Linux/macOS: aliyun

The executable file is corrupted

If none of the preceding solutions resolve the issue, but Cloud Assistant CLI still cannot run, uninstall Cloud Assistant CLI and then install it again.

The version returned by the aliyun version command is different from the installed version

An update method that does not match the initial installation method was used to update Cloud Assistant CLI

For example, you installed Cloud Assistant CLI using Homebrew in macOS and then used a PKG installer to update it. This may cause the system command to still point to the old version after the software update. This issue is usually caused by the priority of the PATH environment variable or a residual symbolic link.

We recommend that you uninstall all versions of Alibaba Cloud CLI and then reinstall it for your operating system.

The old installation path was not used to update Cloud Assistant CLI, but the PATH variable still points to the old path

Uninstall the old version of Cloud Assistant CLI, delete the environment variable, and then reconfigure the environment variable.

The aliyun command can still be used after Alibaba Cloud CLI is uninstalled

An uninstallation method that does not match the initial installation method was used to uninstall Cloud Assistant CLI

Completely uninstall Cloud Assistant CLI using the method that corresponds to its installation method. For example, if you installed Cloud Assistant CLI using Homebrew in macOS, you must use Homebrew to uninstall it.

If you are not sure how Cloud Assistant CLI was installed, try all uninstallation methods for your operating system until the aliyun version command no longer returns any version information.

Other versions of Cloud Assistant CLI are installed

After you perform the uninstallation, other versions of Cloud Assistant CLI may still be installed elsewhere on your system. Uninstall all versions of Cloud Assistant CLI based on your operating system until the aliyun version command no longer returns any version information.

The command is not recognized

The command is not case-sensitive

Because OpenAPI parameter names are case-sensitive, Cloud Assistant CLI parameter names are also case-sensitive. Some parameter values are not case-sensitive. However, to ensure consistent writing standards, we recommend that you also treat parameter values as case-sensitive.

Refer to the OpenAPI document to check for and correct any spelling or format errors in the command.

The command format is incorrect

If the command format is incorrect, Cloud Assistant CLI may fail to parse the command. For example, you use an ROA-style command format to call an RPC-style API.

See Command structure and the corresponding OpenAPI documentation to check for and correct possible spelling or format errors in the command.

The command is built abnormally

The Cloud Assistant CLI lets you use variables to build commands. If a variable is empty or contains only spaces, the CLI may fail to parse the command.

Check whether the variable has a value and whether the value is as expected.

The Cloud Assistant CLI version is too old

If your Cloud Assistant CLI version is too old, it may not support the features or products you need. For example, Cloud Assistant CLI introduced support for CloudSSO credentials in version v3.0.271. Earlier versions cannot recognize the configuration command.

Update Cloud Assistant CLI to the latest version.

String parsing is abnormal

Different shell terminals may have different quoting rules

When you build a command, you must modify the quoting format based on the terminal type. Enable call logs or use the dry run feature to check the details of the passed parameters. For more information, see Parameter format.

When you call an ROA-style OpenAPI, you can use the --body-file option to directly pass a JSON file. This bypasses the terminal's quoting rules.

Some special symbols cannot be correctly parsed in a shell terminal

Passing some special characters directly in the parameter section may cause the command to fail to parse. Escape the characters before passing them. If the command still fails to parse, try passing the parameter in the --key=value format. For more information, see Special characters.

A "required parameters not assigned" error occurs when you call an API

Cloud Assistant CLI validates parameters before calling an API. If a required parameter is missing, an error message such as required parameters not assigned is returned. For example, if the instance ID is missing, the error message is ERROR: required parameters not assigned: --InstanceId.

Check the following items:

See the API documentation to confirm the required parameters. Ensure that the required parameter values are correct.
Ensure that the values you enter for the required parameters are correct. For example, check whether the mobile number format meets the requirements.

You can also use the automatically generated command examples in the OpenAPI Portal. For more information, see Generate and call a command.

A "fail to set configuration" error occurs when you configure identity credentials

When you use the aliyun configure set command to configure credentials, the parameters are validated. If a required parameter is missing, an error message such as fail to set configuration is returned. For example, if a region ID is not specified, the error message is fail to set configuration: region can't be empty.

See Configure credentials and Manage multiple credential configurations to check whether all required credential parameters are included. If the configuration always fails, try using the aliyun configure command to configure identity credentials in interactive mode.

Network connection timeout

The client cannot connect to the network or the connection is unstable

Use the ping or curl command to test the connectivity between the local host and the product endpoint. For example, if the call to the ECS DescribeInstances API times out, use ping ecs.cn-qingdao.aliyuncs.com or curl -v ecs.cn-qingdao.aliyuncs.com to test the connectivity.

If the command times out or does not respond, check whether a blocking policy is set in the firewall or router.
If the network is unstable, switch to a different network environment.

The API processing time is too long

The API processing time may be long and exceed the preset timeout period. You can modify the timeout period in the following ways:

Run the aliyun configure set command with the --read-timeout and --connect-timeout options to modify the timeout period in the configuration. This increases the timeout period to accommodate a longer API response time.
Use the --read-timeout and --connect-timeout options in the command line to modify the timeout period for only the current command.

Invalid credentials

An unexpected credential configuration was used

Cloud Assistant CLI supports saving multiple configurations. If you use an unexpected configuration when you call an API, the call may fail. Before you run a command, you can check the current configuration and switch to the correct one to resolve this issue.

The credential information is incorrect

When you configure identity credentials in interactive mode in Cloud Assistant CLI, their validity is checked when the configuration process is complete. However, when you configure identity credentials in non-interactive mode, Cloud Assistant CLI only checks whether the required parameters are empty and cannot verify the validity of the credentials.

You can check the credential information saved in the configuration and correct any errors to resolve this issue.

The temporary credentials have expired

Cloud Assistant CLI provides multiple credential types. Some credential types may become invalid. For example:

StsToken: The StsToken type uses static temporary credentials. The credentials become invalid when they expire.
External: The External type obtains credentials through an external program. If you use this credential type, ensure that the external program implements a periodic refresh mechanism.
CredentialsURI: The CredentialsURI type obtains credentials by accessing a specified URI. If you use this credential type, you must periodically refresh the credential information saved in the URI.

You must check the credential mode to ensure that Cloud Assistant CLI can obtain valid identity credentials.

Error messages

The following table lists common error codes for Cloud Assistant CLI and related information. For error codes returned when you call an OpenAPI, you can find diagnostic solutions and log information in OpenAPI Explorer.

Error Details

Error description	Possible cause	Solution
unknown profile <PROFILE_NAME>, run configure to check	The specified credential configuration does not exist in the configuration file.	Run the `aliyun configure list/get` command to check the configuration name. Run the `aliyun configure`/`aliyun configure set` command to create a credential configuration.
unexpected authenticate mode: <CREMODE>	An incorrect credential type was specified when you ran the `aliyun configure` command.	Specify the correct credential type when you run the `aliyun configure` command.
the --profile <profileName> is required	A credential configuration was not specified when you ran the `aliyun configure switch` command.	Use the `--profile` option to specify a credential configuration when you run the command.
the profile `<profileName>` does not exist	The credential configuration specified when you ran the `aliyun configure switch` command does not exist.	Run the `aliyun configure list/get` command to check the configuration details.
fail to set configuration: <Error Message>	When you use the `aliyun configure set` command to configure credentials, the required parameters are not passed correctly.	A "fail to set configuration" error occurs when you configure identity credentials
AccessKeyId/AccessKeySecret is empty! run `aliyun configure` first	The AccessKey ID or AccessKey secret in the specified credential configuration is empty.	Run the `aliyun configure get` command to check the configuration details. Run the `aliyun configure`/`aliyun configure set` command to modify the credential configuration.
default RegionId is empty! run `aliyun configure` first	The region ID in the specified credential configuration is empty.
cannot load the source profile: <profileName>	When you use a ChainableRamRoleArn type credential configuration, the name of the preceding credential configuration is incorrect.
invalid credentials uri	When you use a CredentialsURI type credential configuration, the credential URI in the configuration is empty.
unexpected credential mode: <Mode>	The specified credential configuration type is incorrect.
get credentials from <Credentials URI> failed, status code <StatusCode>	When you use a CredentialsURI type credential configuration, the credential URI in the configuration cannot be accessed.	Run the `aliyun configure get` command to check the configuration details. Check the validity of the credential URI. Check whether the network status of the current device is normal. Run the `aliyun configure`/`aliyun configure set` command to modify the credential configuration.
unmarshal credentials failed, the body <Credentials Body>	When you use a CredentialsURI type credential configuration, the credential data `Credentials Body` obtained from the credential URI cannot be deserialized.
get sts token err, Code is not Success	When you use a CredentialsURI type credential configuration, the credential information cannot be obtained from the credential URI.
required parameters not assigned	A required parameter was not specified when you called the OpenAPI.	Check the command and parameter format. Update or reinstall Cloud Assistant CLI.
unchecked version <OpenAPI Version>	An incorrect version was specified when you called the OpenAPI.
too many arguments	The command format does not meet the requirements for calling the OpenAPI.
invalid argument	The command format does not meet the requirements for calling the RPC-style OpenAPI.
product '<ProductCode>' need restful call	The request method was not specified when you called the ROA-style OpenAPI.
bad restful path <PathPattern>	An invalid request path `PathPattern` was specified when you called the ROA-style OpenAPI.
--method value <Method> is not supported, please set method in {GET\|POST}	An unsupported request method was specified when you called the RPC-style OpenAPI.	The `--method` option supports only the `GET`/`POST` request method.
invalid flag --header `<RequestHeader>` use `--header HeaderName=Value	The parameter format does not meet the requirements for using the `--header` option.	The `--header` option supports specifying a request header only in the `key=value` format.
missing version for product <ProductCode>	When you use the `--force` option, the `--version` option was not used to specify the OpenAPI version.	Use the `--version` option to specify the OpenAPI version.
missing region for product <ProductCode>	When you use the `--force` option, the `--region` option was not used to specify the region ID.	Use the `--region` option to specify the region ID.
unknown endpoint for <ProductCode>/<RegionID>!	When you use the `--force` option, an invalid endpoint address was specified.	Check whether the product code and region ID are correct. Use the `--endpoint` option to specify the correct endpoint.
you need to assign col=col1,col2,... with --output	When you use the `--output` option, a filter field value was not specified.	See Filter and format output results in a table and specify the field name based on the response.
jmespath: '<rows>' failed	When you use the `--output` option, the specified filter field path `rows` does not conform to JMESPath specifications.	See the official JMESPath documentation and correct the filter field path `rows` based on JMESPath format specifications.
jmespath: '<rows>' failed Need Array Expr	When you use the `--output` option, the specified filter field path `rows` cannot match the target data.	See the OpenAPI documentation and correct the filter field path `rows`.
colNames: <cols> must be string:number format, like 'name:0', 0 is the array index	When you use the `--output` option to process a JSON array, the filter field value `cols` has an incorrect format.	When you use the `--output` option to process a JSON array, you must specify the filter field value `cols` in the `string:number` format.
read json from <MetadatasPath> failed	Failed to obtain OpenAPI metadata.	Update or reinstall Cloud Assistant CLI.
unmarshal json <MetadatasPath> failed	Failed to deserialize the OpenAPI metadata JSON file.	Update or reinstall Cloud Assistant CLI.
jmespath: '<Field>' failed	When you use the `--pager` option, the specified field format does not conform to JMESPath specifications.	See the OpenAPI documentation and the official JMESPath documentation, and correct the field parameter based on JMESPath format specifications.
jmespath search failed	When you use the `--pager` option, the specified path field `path` does not conform to JMESPath specifications.
jmespath result empty: <path>	When you use the `--pager` option, the specified path field `path` is invalid.
cannot auto recognize collections path: you need add `--pager path=[jmespath]` to assign manually	When you use the `--pager` option, the data collection path cannot be automatically identified.	See the OpenAPI documentation and the official JMESPath documentation, and use the `path` field to specify the data collection path.
unmarshal failed	Failed to deserialize the response data.	Check the command and parameter format. Check whether the network status of the current device is normal. Update or reinstall Cloud Assistant CLI.
jmespath search failed	JMESPath failed to parse the response data.
object <Response> is not string	Failed to convert the API response data to a string.
'--<Param>' is not a valid parameter or flag	An invalid parameter or option `Param` was used when you called the OpenAPI.	See the OpenAPI documentation or help information and correct the parameter or option.
invalid flag --header `<value>` use `--header HeaderName=Value`	An incorrect command format was used to set the request header.	Use the `--header HeaderName=Value` format to set the request header.
unknown parameter position; <PARAM_NAME> is <PARAM_POSITION>	Metadata error.	Add the `--method POST --force` option to the end of the command to force the call.

Technical support

The preceding solutions are intended to help you use Cloud Assistant CLI more easily. If you encounter other issues, submit feedback on GitHub Issues or open a ticket to help us improve the Cloud Assistant CLI experience.

References

If you encounter an issue when you use the aliyun oss command, see ossutil FAQ.