排查並修複阿里雲CLI錯誤 - 阿里雲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體驗。