CLI常见错误排查-阿里云帮助中心

本文介绍阿里云CLI使用过程中的常见错误及其排查步骤。

一般错误排查方式

在使用阿里云CLI的过程中，如您遇到问题或收到错误信息，请优先检查以下内容，以协助您进行错误排查。

检查网络状态

客户端与服务器之间如存在网络异常，可能导致请求无法到达服务器。请检查您的网络状态，以确保您能够访问阿里云的API。

检查是否缺失选项

部分命令存在必需选项，若您在命令中未使用必需选项或传入了异常选项值，则命令无法正常执行。您可通过以下方式查看命令详解或接口详情。

配置凭证时参考配置凭证及多凭证管理，检查是否携带配置命令必需选项。
调用OpenAPI时，可在对应接口文档中查看必需选项信息。
使用--force选项强制调用接口时必须配合--version选项指定需要调用的OpenAPI版本。

检查命令及参数格式

如果阿里云CLI提示您某个命令不存在或无法识别可用参数，则说明您当前执行的命令或参数格式可能存在错误。您可以通过以下方式进行命令自检：

参考命令结构及对应OpenAPI文档，检查命令是否存在拼写或格式错误。
检查传入参数是否正确。
检查传入参数是否包含需要处理的特殊字符。更多信息，请参见参数格式。

检查地域及接入点

如果阿里云服务不支持以您指定的接入点或地域发起调用，或者待访问资源位于其他地域，则调用时有可能出现错误，阿里云CLI服务接入点与地域优先级如下所示：

--endpoint选项指定的接入点信息。
--region选项指定的地域ID。
凭证配置profile中保存的地域ID。
环境变量ALIBABA_CLOUD_REGION_ID中保存的地域ID。

检查请求详情

在使用阿里云CLI的过程中，如果执行命令后的结果与预期不符，您可以通过以下方式确认请求参数是否按预期方式拼接。

使用模拟调用功能查看请求详情

使用--dryrun选项开启模拟调用，此次操作不会对您的云资源产生任何实际影响。使用模拟调用功能后输出身份凭证、使用地域、API版本等信息。更多信息，请参见模拟调用功能。

启用并检查阿里云CLI日志

启用日志输出功能后，阿里云CLI将在命令执行时为您打印更加详细的调用信息。具体操作，请参见模拟调用功能。

确认凭证有效性

如果您未能正确配置身份凭证信息，则有可能在发起调用时产生各种错误。您可以检查以下内容以确保身份凭证的有效性：

检查当前使用的配置

如果使用非预期的凭证配置发起调用，执行命令后的结果可能与预期不符。阿里云CLI凭证配置优先级如下所示：

--profile选项指定的配置。
环境变量ALIBABA_CLOUD_PROFILE指定的配置。
使用aliyun configure switch命令指定的当前配置。更多信息，请参见设定当前凭证配置。

检查配置中保存的凭证信息

如果配置中保存的凭证信息有误，阿里云CLI无法使用此配置调用OpenAPI。您可以通过以下方式检查凭证信息：

执行aliyun configure list命令查看全部凭证配置的概要信息。
执行aliyun configure get命令查看单个凭证配置的详细信息。

若凭证信息存在错误，您可尝试重新配置身份凭证，或使用aliyun configure set命令修改已保存的凭证信息。具体操作，请参见修改指定身份凭证配置。

检查凭证模式

在使用RamRoleArn、EcsRamRole等凭证模式时，您需要检查凭证Provider是否可以正常工作。若阿里云CLI无法获取有效的身份凭证则会引起接口调用失败。

RamRoleArn、ChainableRamRoleArn：使用此凭证模式需确保已为RAM用户或RAM角色授予STS的管理权限（AliyunSTSAssumeRoleAccess）。更多信息，请参见AssumeRole - 获取扮演角色的临时身份凭证。
EcsRamRole：使用此凭证模式需参考权限示例为当前用户身份授予相应权限。
External、CredentialsURI：使用此凭证模式需检查外部程序命令能否正常获取凭证。

凭证对应的身份是否具备访问权限

如果您使用的凭证信息正确，则有可能您当前的身份并不具备执行当前操作所需的权限。请您为当前身份授予所需权限后重新尝试执行命令。

更新或重新安装阿里云CLI版本

阿里云CLI通常会随着版本更新引入新的支持内容，可能包括阿里云服务、功能及参数等。新的支持内容仅可在首次引入该内容后发布的阿里云CLI版本中使用。如果您已确认命令及参数格式均无错误，但阿里云CLI仍提示您命令不存在或无法识别可用参数，建议您尝试重新安装或更新到最新版本的阿里云CLI。

常见问题

找不到aliyun命令

安装完成后未重新启动终端

修改PATH环境变量后，需重新启动终端会话才能生效。请尝试重新启动所有终端会话以解决此问题。

环境变量PATH未更新或配置了错误的安装路径

执行以下命令查看当前环境变量PATH，检查环境变量中是否包含正确的安装目录路径。

Linux/macOS

echo $PATH

Windows PowerShell

echo $Env:PATH

Windows命令提示符CMD

echo %PATH%

可执行文件丢失

请检查可执行文件是否位于阿里云CLI安装目录下。若该文件被删除或移动至其他目录，则阿里云CLI无法正常运行。您可能需要重新安装阿里云CLI。

Windows系统中可执行文件：aliyun.exe

Linux/macOS系统中可执行文件：aliyun

可执行文件损坏

若以上均无异常，阿里云CLI仍无法正常运行。建议您卸载阿里云CLI之后重新执行安装操作。

执行aliyun version命令时返回的版本与安装的版本不同

更新阿里云CLI时使用了与初始安装方式不匹配的更新方式

例如，在macOS系统中通过Homebrew安装阿里云CLI后，使用PKG安装包进行更新。此时可能会导致系统命令在软件更新后仍指向旧版本。该现象通常由 PATH 环境变量优先级或残留软链接引起。

建议您卸载所有版本的阿里云CLI后，根据操作系统重新执行安装操作。

更新阿里云CLI时未使用旧安装路径，但PATH变量仍指向旧路径

建议您卸载旧版本阿里云CLI并删除环境变量后，重新配置环境变量。

卸载阿里云CLI后仍能使用aliyun命令

卸载阿里云CLI时使用了与初始安装方式不匹配的卸载方式

建议您根据安装方式，完整执行相应的卸载操作。例如，在macOS系统中通过Homebrew安装阿里云CLI后，需要使用Homebrew执行卸载操作。

若您不确定阿里云CLI的安装方式，可根据操作系统尝试执行所有卸载操作，直至aliyun version不再返回任何版本信息。

安装了其他版本的阿里云CLI

若您已执行卸载操作，则可能在系统中的其他位置仍安装有阿里云CLI。建议您根据操作系统卸载所有版本的阿里云CLI，直至aliyun version不再返回任何版本信息。

无法识别命令

命令未区分大小写

由于OpenAPI参数名严格区分大小写，因此阿里云CLI的参数名输入同样严格区分大小写。部分参数值不区分大小写。但为确保书写规范的一致性，建议您同样严格区分参数值的大小写。

建议您参考OpenAPI文档，检查并修正命令可能存在的拼写或格式错误。

命令格式错误

若命令格式存在错误，可能导致阿里云CLI在解析命令时发生错误。例如：使用ROA风格命令格式调用RPC风格API。

参考命令结构及对应OpenAPI文档，检查并修正命令可能存在的拼写或格式错误。

命令构建异常

阿里云CLI支持以变量形式构建命令，若变量为空值或仅包含空格，则可能导致阿里云CLI在解析命令时发生错误。

您需要检查变量值是否存在，以及变量值是否与预期一致。

阿里云CLI当前版本过低

若阿里云CLI版本过低，则可能无法提供您所需要的功能或产品支持。例如：阿里云CLI自v3.0.271版本起引入CloudSSO类型凭证，若小于该版本则无法识别配置命令。

建议您及时更新到最新版本的阿里云CLI。

字符串解析异常

不同的Shell终端在引用规则上可能存在差异

在构建命令时，您需要根据终端类型修正引用格式，开启调用日志或使用模拟调用功能可检查传入参数的详细信息。更多信息，请参见参数格式。

调用ROA风格OpenAPI时，可使用--body-file选项直接传入JSON文件，从而绕过终端的引用规则。

部分特殊符号在Shell终端中无法正确解析

在参数部分直接传入部分特殊符号可能导致命令解析失败，请将符号转义后再传入。若仍无法解析，您可尝试使用--key=value的格式传入参数。具体操作，请参见特殊字符。

调用API时发生“required parameters not assigned”类型错误

阿里云CLI调用API之前会对参数进行校验，如果缺少必要参数，您将收到类似required parameters not assigned的错误提示。例如，如果实例ID缺失，会报错：ERROR: required parameters not assigned: --InstanceId。

建议您检查以下内容：

参考API文档确认必填项。确保必填参数值正确。
确保填写的必填参数值正确无误，例如手机号格式等是否符合要求。

您也可在OpenAPI门户中使用自动生成的命令示例。更多信息，请参见生成并调用命令。

配置身份凭证时发生“fail to set configuration”类型错误

使用aliyun configure set命令配置凭证时会对参数进行校验，如果缺少必要参数，您将收到类似fail to set configuration的错误提示。例如，如果未指定地域ID，会报错：fail to set configuration: region can't be empty。

建议您参考配置凭证及多凭证管理，检查凭证必要参数是否完整。如始终配置失败，请尝试使用aliyun configure采用交互式方式配置身份凭证。

网络连接超时

客户端无法连接网络或连接不稳定

使用ping或curl命令测试本地主机与云产品Endpoint之间连通性，例如调用ECSDescribeInstances接口超时，使用ping ecs.cn-qingdao.aliyuncs.com或curl -v ecs.cn-qingdao.aliyuncs.com测试连通性。

若命令执行超时或无响应，请检查防火墙或路由器中是否设置阻断策略。
对于网络不稳定的情况，建议更换网络环境。

接口处理时间过长

接口处理时间可能过长，超过预设的超时时间。您可通过以下方式修改超时时间：

使用aliyun configure set命令和--read-timeout、--connect-timeout选项修改配置中的超时时间，通过增加超时时间适应较长的接口响应时间。
在命令行中使用--read-timeout和--connect-timeout选项，仅修改当前命令的超时时间。

凭证无效

使用了非预期的凭证配置

阿里云CLI支持保存多套配置，如果在调用API时如果使用了非预期的配置，则有可能导致调用失败。您可以在执行命令前检查当前使用的配置并切换到正确的配置以解决此问题。

凭证信息错误

在阿里云CLI中使用交互式方式配置身份凭证，在完成配置流程时会进行有效性校验。但在使用非交互式方式配置身份凭证时，阿里云CLI仅校验必需参数是否为空，无法验证凭证有效性。

您可以尝试检查配置中保存的凭证信息并修正错误的凭证信息以解决此问题。

临时凭证过期

阿里云CLI提供多种凭证类型，部分凭证类型可能出现凭证失效的问题。例如：

StsToken：StsToken类型使用静态临时凭证，凭证过期即失效。
External：External类型凭证通过外部程序获取凭证，如使用此类型凭证需确保外部程序实现定期刷新机制。
CredentialsURI：CredentialsURI类型凭证通过访问用户输入的URI地址获取凭证，如使用此类型凭证需定期刷新URI中保存凭证信息。

您需要检查凭证模式以确保阿里云CLI可以获取有效的身份凭证。

错误信息列表

以下表格为您展示阿里云CLI常见错误码及相关信息。调用OpenAPI时返回的错误码，您可在OpenAPI问题诊断中获取诊断方案与日志信息。

错误详情

错误描述	可能的原因	处理方式
unknown profile <PROFILE_NAME>, run configure to check	配置文件中不存在指定凭证配置。	执行`aliyun configure list/get`命令检查配置名称。执行`aliyun configure`/`aliyun configure set`命令创建凭证配置
unexpected authenticate mode: <CREMODE>	执行`aliyun configure`命令时指定了错误的凭证类型。	执行`aliyun configure`命令时指定正确的凭证类型。
the --profile <profileName> is required	执行`aliyun configure switch`命令时未指定凭证配置。	执行命令时使用`--profile`选项指定凭证配置。
the profile `<profileName>` is inexist	执行`aliyun configure switch`命令时指定的凭证配置不存在。	执行`aliyun configure list/get`命令检查配置详情。
fail to set configuration: <Error Message>	使用`aliyun configure set`命令配置凭证时，未正确传入必要参数。	配置身份凭证时发生“fail to set configuration”类型错误
AccessKeyId/AccessKeySecret is empty! run `aliyun configure` first	指定凭证配置中的AccessKey ID或AccessKey Secret为空。	执行`aliyun configure get`命令检查配置详情。执行`aliyun configure`/`aliyun configure set`命令修改凭证配置。
default RegionId is empty! run `aliyun configure` first	指定凭证配置中的地域ID为空。
can not load the source profile: <profileName>	使用ChainableRamRoleArn类型凭证配置时，配置中的前置凭证配置名称有误。
invalid credentials uri	使用CredentialsURI类型凭证配置时，配置中的凭证URI为空。
unexpected certificate mode: <Mode>	指定凭证配置类型存在错误。
get credentials from <Credentials URI> failed, status code <StatusCode>	使用CredentialsURI类型凭证配置时，配置中的凭证URI无法访问。	执行`aliyun configure get`命令检查配置详情。检查凭证URI有效性。检查当前设备网络状态是否正常。执行`aliyun configure`/`aliyun configure set`命令修改凭证配置。
unmarshal credentials failed, the body <Credentials Body>	使用CredentialsURI类型凭证配置时，无法反序列化从凭证URI中获取的凭证数据`Credentials Body`。
get sts token err, Code is not Success	使用CredentialsURI类型凭证配置时，无法从凭证URI中获取凭证信息。
required parameters not assigned	调用OpenAPI时，未指定必填参数。	检查命令及参数格式。更新或重新安装阿里云CLI版本。
unchecked version <OpenAPI Version>	调用OpenAPI时，指定了错误的版本信息。
too many arguments	调用OpenAPI时，命令格式与要求不符。
invalid argument	调用RPC风格OpenAPI时，命令格式与要求不符。
product '<ProductCode>' need restful call	调用ROA风格OpenAPI时，未指定请求方式。
bad restful path <PathPattern>	调用ROA风格OpenAPI时，指定了无效的请求路径`PathPattern`。
--method value <Method> is not supported, please set method in {GET\|POST}	调用RPC风格OpenAPI时，指定了不支持的请求方式。	`--method`选项仅支持指定`GET`/`POST`请求方式。
invalid flag --header `<RequestHeader>` use `--header HeaderName=Value	使用`--header`选项时，传参格式与要求不符。	`--header`选项仅支持使用`key=value`形式指定请求头。
missing version for product <ProductCode>	使用`--force`选项时，未使用`--version`选项指定OpenAPI版本信息。	使用`--version`选项指定OpenAPI版本。
missing region for product <ProductCode>	使用`--force`选项时，未使用`--region`选项指定地域ID。	使用`--region`选项指定地域ID。
unknown endpoint for <ProductCode>/<RegionID>!	使用`--force`选项时，指定了无效的接入点地址。	检查产品代码及地域ID是否正确。使用`--endpoint`选项指定正确的接入点。
you need to assign col=col1,col2,... with --output	使用`--output`选项时，未指定过滤字段值。	参考文档过滤且表格化输出结果，根据响应结果指定字段名。
jmespath: '<rows>' failed	使用`--output`选项时，指定的过滤字段路径`rows`格式与JMESPath规范不符。	参考JMESPath官方文档，根据JMESPath格式规范修正过滤字段路径`rows`。
jmespath: '<rows>' failed Need Array Expr	使用`--output`选项时，指定的过滤字段路径`rows`无法匹配到目标数据。	参考OpenAPI文档，修正过滤字段路径`rows`。
colNames: <cols> must be string:number format, like 'name:0', 0 is the array index	使用`--output`选项处理JSON数组时，过滤字段值`cols`格式错误。	使用`--output`选项处理JSON数组时，需以`string:number`的格式指定过滤字段值`cols`。
read json from <MetadatasPath> failed	无法获取OpenAPI元数据。	更新或重新安装阿里云CLI版本。
unmarshal json <MetadatasPath> failed	无法反序列化OpenAPI元数据JSON文件。	更新或重新安装阿里云CLI版本。
jmespath: '<Field>' failed	使用`--pager`选项时，指定的字段格式不符合JMESPath规范。	参考OpenAPI文档及JMESPath官方文档，根据JMESPath格式规范修正字段参数。
jmespath search failed	使用`--pager`选项时，指定的路径字段`path`格式不符合JMESPath规范。
jmespath result empty: <path>	使用`--pager`选项时，指定的路径字段`path`无效。
can't auto recognize collections path: you need add `--pager path=[jmespath]` to assign manually	使用`--pager`选项时，无法自动识别数据集合路径。	参考OpenAPI文档及JMESPath官方文档，使用`path`字段指定数据集合路径。
unmarshal failed	无法反序列化响应数据。	检查命令及参数格式。检查当前设备网络状态是否正常。更新或重新安装阿里云CLI版本。
jmes search failed	JMESPath无法解析响应数据。
object <Response> isn't string	无法将接口响应数据转化为string格式字符串。
'--<Param>' is not a valid parameter or flag	调用OpenAPI时，使用了无效的参数或选项`Param`。	参考OpenAPI文档或帮助信息，修正所用参数或选项。
invaild flag --header `<value>` use `--header HeaderName=Value`	设置请求头时，使用了错误的命令格式。	使用`--header HeaderName=Value`格式设置请求头。
unknown parameter position; <PARAM_NAME> is <PARAM_POSITION>	元数据错误。	在命令后添加`--method POST --force`选项发起强制调用。

技术支持

以上问题的解决方案旨在帮助您更友好地使用阿里云CLI。如果您在使用过程中遇到其他问题，可以通过GitHub Issues或工单提交反馈，帮助我们共同改进阿里云CLI体验。