오류 범주
Azure CLI에서 반환되는 대부분의 오류는 다음 범주 중 하나에 속합니다.
| 오류 범주 | 일반 오류 원인 |
|---|---|
| 인식할 수 없는 인수 | 매개 변수의 철자가 잘못되었거나 존재하지 않습니다. |
| 필수 인수 누락 | 필수 매개 변수가 지정되지 않았거나 두 개의 "매개 변수 쌍" 중 하나만 지정됩니다. 매개 변수의 철자가 잘못되었을 수도 있습니다. |
| 상호 배타적 매개변수 | 둘 이상의 매개 변수를 함께 지정할 수 없습니다. |
| 잘못된 인수 값 |
매개 변수 값 유효하지 않습니다. 이 오류는 따옴표, 이스케이프 문자 또는 공백 때문에 자주 발생합니다. |
| 잘못된 요청 | HTTP 상태 코드 400은 이 오류를 반환합니다. 공백이 누락되었는지, 매개변수 대시가 누락되었는지, 또는 작은따옴표나 큰따옴표가 추가되었거나 누락되었는지 확인하세요. 이 오류는 매개 변수 값에 허용되는 값이 없는 경우에도 발생합니다. |
| 리소스를 찾을 수 없습니다 | 매개 변수 값에서 참조되는 Azure 리소스를 찾을 수 없습니다. |
| 인증 | Microsoft Entra 인증에 실패했습니다. |
디버그 매개 변수
각 참조 명령에 대해 실행 중인 Azure CLI를 확인하는 가장 좋은 방법 중 하나는 매개 변수를 --debug 사용하는 것입니다. 다음은 실패한 명령과 성공한 명령 모두에 대한 예 --debug 입니다.
# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug
다음은 디버그 출력의 부분입니다. 로그 위치 및 인식할 수 없는 인수를 확인합니다.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...
이전 예제에서 제공된 오류 --debug 출력을 성공적인 실행과 비교합니다.
# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug
다음은 디버그 출력의 부분입니다. 로그 위치, API 호출 및 런타임을 확인합니다.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies: 'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies: 'Content-Length': '23'
cli.azure.cli.core.sdk.policies: 'Accept': 'application/json'
cli.azure.cli.core.sdk.policies: 'x-ms-client-request-id': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies: 'CommandName': 'group create'
cli.azure.cli.core.sdk.policies: 'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies: 'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies: 'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies: 'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)
JSON 서식 지정에 대한 --debug 예제는 스크립팅 언어 간의 따옴표로 묶는 차이점 - JSON 문자열참조하세요.
일반적인 구문 오류
Azure CLI는 Bash, PowerShell 및 Windows 명령 프롬프트(cmd.exe)에서 실행할 수 있지만 스크립팅 언어 간에는 구문 차이가 있습니다. 작은따옴표, 큰따옴표 및 이스케이프 문자를 포함하는 Azure CLI 스크립트는 언어 간에 복사할 때 수정이 필요한 경우가 많습니다. 이 문제는 매개 변수 값, 특히 매개 변수에 할당된 --query 값에서 가장 자주 표시됩니다. 다음은 몇 가지 일반적인 오류 메시지입니다.
잘못된 요청, ... {something}이 잘못되었습니다. 이 오류는 공백, 작은따옴표, 큰따옴표의 사용 또는 따옴표 부족으로 인해 발생할 수 있습니다.
예기치 않은 토큰...: 이 오류는 추가 공간 또는 따옴표가 있을 때 표시됩니다.
잘못된 jmespath_type 값: 이 오류는 매개변수에서 따옴표가 잘못 사용되어 발생하는 경우가 많습니다.
변수 참조가 유효하지 않습니다. 문자열의 형식이 제대로 지정되지 않은 경우 연결 또는 누락된 이스케이프 문자로 인해 이 오류가 수신됩니다.
인식할 수 없는 인수: 이 오류는 종종 잘못된 줄 연속 문자 또는 철자가 잘못된 매개 변수 이름으로 인해 발생합니다.
단항 연산자 뒤의 식 누락: 줄 연속 문자가 누락된 경우 이 오류가 표시됩니다.
구문 오류를 설명하고 작업 예제를 제공하는 데만 사용되는 몇 가지 Azure CLI 문서가 있습니다.
- 스크립팅 언어 간의 차이점 인용
- Bash, PowerShell 및 Cmd 튜토리얼의 구문 차이점
- Azure CLI 명령 출력을 JMESPath 쿼리를 사용하여 쿼리하는 방법
에서 많은 매개 변수 예제를 찾습니다. - Bash 스크립팅 언어에서 Azure CLI를 사용하는 방법
- PowerShell 스크립팅 언어로 Azure CLI를 실행하기 위한 고려 사항
팁 (조언)
명령 오류를 해결할 수 없는 경우 다른 스크립팅 언어를 사용해 보세요. 대부분의 Azure CLI 설명서는 Bash 스크립팅 언어를 사용하는 Azure Cloud Shell에서 작성 및 테스트됩니다. Bash에서 실행할 문서 예제를 가져올 수 있지만 PowerShell에서 실행되지 않는 경우 작은따옴표와 큰따옴표 및 이스케이프 문자 사용을 검토합니다.
MFA(다단계 인증) 문제 해결
대화형 로그인 실패
리소스를 만들거나 수정하거나 삭제하는 Azure CLI 명령을 실행할 때 오류가 발생하는 경우 MFA(다단계 인증)가 필요한 Microsoft Entra ID 조건부 액세스 정책으로 인해 문제가 발생할 수 있습니다.
이러한 오류는 일반적으로 정책에서 MFA가 필요하지만 로그인하는 동안 적용되지 않는 경우에 발생합니다.
정책에 의해 리소스가 허용되지 않음
사용할 때 다음 오류 중 하나가 표시될 수 있습니다.
- Azure CLI 버전 2.75.0 이하
Due to a configuration change made by your administrator, or because you moved to a new location,
you must enroll in multi-factor authentication. Interactive authentication is needed.
또는:
Resource was disallowed by policy. Reasons: MFA is required. See error details for policy resource
IDs. RequestDisallowedByPolicy Message: Resource policy resource IDs was disallowed by policy.
Reasons: MFA is required.
또는:
Unauthorized. RequestDisallowedByPolicy. Resource was disallowed by policy. Reasons: MFA is
required. See error details for policy resource IDs. MFA is required. Users must authenticate with
multi-factor authentication to create or update resources.
자세한 오류 메시지 및 정책 세부 정보를 받으려면 다음 버전 이상으로 업그레이드합니다.
- Azure CLI 버전 2.76.0 이상
다음 오류는 특정 작업에 대한 조건부 액세스에서 MFA가 필요한 Azure CLI 2.76.0 이상에서 발생합니다.
Run the command below to authenticate interactively; additional arguments may be added as needed:
az logout
az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"
(RequestDisallowedByPolicy) Resource was disallowed by policy. Policy identifiers. Users must use
MFA for Create/Update operations. Users must authenticate with multi-factor authentication to create
or update resources. Users must use MFA for Create operation. Users must authenticate with
multi-factor authentication to create or update resources. Users must use MFA for Create/Update
operations. Users must authenticate with multi-factor authentication to create or update resources.
Users must use MFA for Create operation. Users must authenticate with multi-factor authentication to
create or update resources.
해결 옵션
로그인 시 MFA를 적용하도록 Azure 관리자에게 요청합니다. 이렇게 하면 세션이 추가 단계 없이 조건부 액세스 요구 사항을 충족할 수 있습니다.
로그인 시 MFA 적용이 불가능한 경우 매개 변수를
--claims-challenge사용하여 대화형으로 인증합니다.az logout az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"
자세한 내용은 Azure 및 기타 관리 포털에 대한 필수 다단계 인증 계획을 참조하세요.
win32file을 가져오는 동안 DLL 로드가 실패했습니다.
Azure CLI를 사용하려고 할 때 다음 오류가 발생할 수 있습니다.
DLL load failed while importing win32file: The specified module could not be found.
The command failed with an unexpected error. Here is the traceback:
DLL load failed while importing win32file: The specified module could not be found.
Traceback (most recent call last):
File "<frozen runpy>", line 198, in _run_module_as_main
File "<frozen runpy>", line 88, in _run_code
File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/__main__.py", line 13, in <module>
File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/core/telemetry.py", line 19, in <module>
File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\azure/cli/telemetry/__init__.py", line 9, in <module>
File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/__init__.py", line 4, in <module>
File "D:\a\_work\1\s\build_scripts\windows\artifacts\cli\Lib\site-packages\portalocker/portalocker.py", line 11, in <module>
ImportError: DLL load failed while importing win32file: The specified module could not be found.
PS C:\Users\dsevilla>
이 문제는 손상된 설치로 인해 발생할 수 있습니다. 문제를 해결하려면 다음을 수행합니다.
- Azure CLI를 제거합니다.
- 기본 설치 방법을 사용하여 Azure CLI를 다시 설치합니다.
자세한 내용은 GitHub 문제 #32045를 참조하세요.
오류: 잘못된 값이거나 존재하지 않음
이러한 오류는 잘못된 형식을 포함하는 변수 값을 사용하려고 할 때 종종 발생합니다. Azure CLI 기본 출력은 JSON입니다. 변수에 Azure 리소스의 ID를 저장하려는 경우 지정 --output tsv해야 합니다. 예제는 다음과 같습니다.
# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID
# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]
# Try to set your subscription to the new ID
az account set --subscription $subscriptionID
# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.
이제 tsv 출력 형식을 사용합니다.
# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID
# output as TSV
00000000-0000-0000-0000-000000000000
# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID
오류: 인수가 필요하거나 필수입니다.
Azure CLI 명령에 필수 매개 변수가 없거나 Azure CLI에서 참조 명령을 잘못 구문 분석하는 입력 오류가 발생하는 경우 이 오류가 발생합니다. 스크립트로 작업할 때 하나 이상의 조건이 true인 경우에도 이 오류가 발생합니다.
- 줄 연속 문자가 없거나 잘못되었습니다.
- PowerShell 스크립팅 언어로 작업할 때 줄 연속 문자의 오른쪽에 후행 공백이 있습니다. PowerShell 스플래팅 은 Azure CLI 명령이 있는 해시 테이블이 아닌 배열에서만 지원됩니다.
- 변수 이름에는 대시(-)와 같은 특수 문자가 포함됩니다.
오류: 리소스를 찾을 수 없음
Azure CLI가 매개 변수 값에 전달된 리소스 이름 또는 ID를 찾을 수 없는 경우 일반적으로 다음 이유 중 하나로 인해 발생합니다.
- 리소스 이름 또는 ID의 철자가 잘못되었습니다.
- 리소스 이름은 특수 문자를 포함하며 작은따옴표 또는 큰따옴표로 묶지 않습니다.
- 변수에 전달되는 값에는 보이지 않는 선행 또는 후행 공백이 있습니다.
- 리소스가 존재하지만, 다른 구독에 속해 있습니다.
오류: 문자열을 JSON으로 구문 분석하지 못했습니다.
Bash, Linux의 PowerShell, 그리고 Windows의 PowerShell 간에는 인용 부호 처리 방식의 차이점이 있습니다.
또한 PowerShell 버전이 서로 다른 결과를 생성할 수 있습니다. JSON 문자열과 같은 복잡한 매개 변수의 경우 Azure CLI의 @<file> 규칙을 사용하여 셸의 해석을 우회하는 것이 가장 좋습니다. 자세한 내용은 다음 문서 중 하나를 참조하세요.
Bash, PowerShell 및 cmd.exe에 대한 JSON 구문 예제는 스크립팅 언어 간의 따옴표 차이 - JSON 문자열 자습서를 참조하세요.
오류: 잘못된 템플릿 배포
해당 리소스를 제공하지 않는 위치에 Azure 리소스를 만들려고 하면 "다음 SKU가 용량 제한에 실패했습니다. myDesiredSkuName"은 현재 위치 'mySpecifiedLocation'에서 사용할 수 없습니다."라는 메시지와 유사한 오류가 표시됩니다.
westus 위치에서 생성할 수 없는 VM의 전체 오류 예시는 다음과 같습니다.
{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}
솔루션은 요청된 Azure 리소스의 속성을 변경하거나 다른 위치를 시도하는 것입니다.
오류: 구독을 찾을 수 없음
구독 이름 또는 ID를 잘못 입력하지 않았다고 가정하면 이 오류는 리소스 공급자가 활성 구독에 등록되지 않은 경우에 발생합니다. 예를 들어 az storage account create실행하려면 Microsoft.Storage 공급자를 등록해야 합니다. 리소스 공급자를 등록하려면 Azure 리소스 공급자 및 유형을 참조 하세요.
오류: 잘못된 핸드셰이크 인증서 확인 실패
이 오류를 해결하는 방법에 대한 자세한 내용은 프록시 뒤에 있는
프록시 뒤에서 작업
자체 서명된 인증서를 사용하는 프록시 서버에서 Azure CLI를 사용하는 경우 Azure CLI에서 사용하는 Python 요청 라이브러리 다음 오류가 발생할 수 있습니다. SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",).
이 오류를 해결하려면 환경 변수 REQUESTS_CA_BUNDLE PEM 형식의 CA 번들 인증서 파일 경로로 설정합니다.
| 운영 체제 | 기본 인증 기관 번들 |
|---|---|
| Windows 32비트 | C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Windows 64비트 | C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
| Ubuntu/Debian Linux | /opt/az/lib/python<version>/site-packages/certifi/cacert.pem |
| CentOS Stream/RHEL/SUSE Linux | /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem |
| macOS | Intel 모델: /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem 실리콘 모델: /opt/homebrew/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem |
CA 번들 인증서 파일에 프록시 서버의 인증서를 추가하거나 내용을 다른 인증서 파일에 복사합니다. 그런 다음 REQUESTS_CA_BUNDLE 새 파일 위치로 설정합니다. 예제는 다음과 같습니다.
<Original cacert.pem>
-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----
일부 프록시에는 인증이 필요합니다.
HTTP_PROXY 또는 HTTPS_PROXY 환경 변수의 형식에는 HTTPS_PROXY="https://username:password@proxy-server:port"같은 인증이 포함되어야 합니다. 자세한 내용은 Python용 Azure SDK프록시를 구성하는 방법을 참조하세요.
서비스 프린시플
서비스 주체 문제 해결에 대한 자세한 내용은 서비스 주체 작업 자습서의 정리 및 문제 해결 참조하세요.
기타 문제
이 문서에 나열되지 않은 Azure CLI에 제품 문제가 발생하는 경우 GitHub문제를 제출합니다.
참고하십시오
- Azure CLI를 성공적으로 사용하기 위한 팁
GitHub에서 Microsoft와 공동 작업
이 콘텐츠의 원본은 GitHub에서 찾을 수 있으며, 여기서 문제와 끌어오기 요청을 만들고 검토할 수도 있습니다. 자세한 내용은참여자 가이드를 참조하세요.
Azure CLI