Problembehandlung bei Azure CLI

Fehlerkategorien

Die meisten fehler, die von der Azure CLI zurückgegeben werden, fallen in eine der folgenden Kategorien:

Der Debugparameter

Eine der besten Möglichkeiten, zu sehen, was die Azure CLI für jeden Verweisbefehl ausführt, ist die Verwendung des --debug Parameters. Hier sind Beispiele für --debug sowohl für einen fehlgeschlagenen als auch für einen erfolgreichen Befehl.

# 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

Hier ist ein Teil der Fehlerbehebungsausgabe. Beachten Sie den Protokollspeicherort und das nicht erkannte Argument.

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
...

Vergleichen Sie die im vorherigen Beispiel angegebene Fehlerausgabe --debug mit einer erfolgreichen Ausführung:

# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug

Hier ist ein Teil der Fehlerbehebungsausgabe. Beachten Sie den Protokollspeicherort, den API-Aufruf und die Laufzeit.

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)

Beispiele für --debug zur JSON-Formatierung finden Sie unter Unterschiede in der Zitation zwischen Skriptsprachen – JSON-Zeichenfolgen.

Häufige Syntaxfehler

Obwohl die Azure CLI in Bash, PowerShell und der Windows-Eingabeaufforderung (cmd.exe) ausgeführt werden kann, gibt es Syntaxunterschiede zwischen Skriptsprachen. Azure CLI-Skripts mit einfachen Anführungszeichen, doppelten Anführungszeichen und Escapezeichen erfordern häufig Änderungen, wenn sie zwischen Sprachen kopiert werden. Diese Herausforderung wird am häufigsten in Parameterwerten angezeigt, insbesondere in parameterwerten, die dem --query Parameter zugewiesen sind. Nachfolgend finden Sie einige häufige Fehlermeldungen:

• Ungültige Anforderung ... {something} ist ungültig: Dieser Fehler kann durch ein Leerzeichen, ein- oder doppeltes Anführungszeichen oder einen Mangel an Anführungszeichen verursacht werden.

• Unerwartetes Token...: Dieser Fehler wird angezeigt, wenn ein zusätzliches Leerzeichen oder Anführungszeichen vorhanden ist.

• Ungültiger jmespath_type Wert: Dieser Fehler kommt häufig aus einer falschen Quotierung im --query Parameter.

• Der Variablenverweis ist ungültig: Dieser Fehler wird empfangen, wenn eine Zeichenfolge nicht ordnungsgemäß formatiert ist, häufig aufgrund von Verkettung oder fehlendem Escapezeichen.

• Nicht erkannte Argumente: Dieser Fehler wird häufig durch ein falsches Zeilenfortsetzungszeichen oder falsch geschriebenen Parameternamen verursacht.

• Fehlender Ausdruck nach dem unären Operator: Dieser Fehler wird angezeigt, wenn ein Zeilenfortsetzungszeichen fehlt.

Es gibt mehrere Azure CLI-Artikel, die sich mit der Erläuterung von Syntaxfehlern und dem Bereitstellen von Arbeitsbeispielen beschäftigen:

• Unterschiede zwischen Skriptsprachen aufzeigen
• Syntaxunterschiede in Bash, PowerShell und Cmd Anleitung
• Finden Sie viele --query Parameterbeispiele in Wie man Azure CLI-Befehlsausgaben mit einer JMESPath-Abfrage abfragt.
• So verwenden Sie die Azure CLI in der Bash-Skriptsprache
• Überlegungen zum Ausführen der Azure CLI in einer PowerShell-Skriptsprache

Problembehandlung bei mehrstufiger Authentifizierung (MFA)

Interaktive Anmeldefehler

Wenn Beim Ausführen von Azure CLI-Befehlen, die Ressourcen erstellen, ändern oder löschen, Fehler auftreten, kann das Problem durch eine Microsoft Entra ID-Richtlinie für bedingten Zugriff verursacht werden, die eine mehrstufige Authentifizierung (MFA) erfordert.

Diese Fehler treten in der Regel auf, wenn MFA von der Richtlinie benötigt wird, während der Anmeldung jedoch nicht erzwungen wird.

Ressource wurde von der Richtlinie nicht zugelassen.

Möglicherweise wird bei der Verwendung eines der folgenden Fehler angezeigt:

• Azure CLI Version 2.75.0 oder früher

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.

Oder:

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.

Oder:

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.

Führen Sie ein Upgrade auf die folgenden Versionen oder höher durch, um informativere Fehlermeldungen und Richtliniendetails zu erhalten:

• Azure CLI Version 2.76.0 oder höher

Der folgende Fehler tritt in Azure CLI 2.76.0+ auf, wobei MFA für bestimmte Vorgänge erforderlich ist.

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.

Lösungsoptionen

• Bitten Sie Ihren Azure-Administrator, MFA bei der Anmeldung zu erzwingen. Auf diese Weise kann Ihre Sitzung die Anforderungen für den bedingten Zugriff ohne zusätzliche Schritte erfüllen.

• Wenn die MFA-Erzwingung bei der Anmeldung nicht möglich ist, verwenden Sie den --claims-challenge Parameter, um interaktiv zu authentifizieren:

  az logout
  az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>"
  

Weitere Informationen finden Sie unter Planen der obligatorischen mehrstufigen Authentifizierung für Azure und andere Verwaltungsportale

Fehler beim Laden der DLL während des Imports von win32file

Beim Versuch, die Azure CLI zu verwenden, tritt möglicherweise der folgende Fehler auf:

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>

Dieses Problem kann aufgrund einer beschädigten Installation auftreten. Das Problem lässt sich wie folgt beheben:

1. Deinstallieren Sie die Azure CLI.
2. Installieren Sie die Azure CLI mit Ihrer bevorzugten Installationsmethode erneut.

Weitere Informationen finden Sie unter GitHub-Problem #32045.

Fehler: Ungültiger Wert oder nicht vorhanden

Diese Fehler treten häufig auf, wenn Sie versuchen, Variablenwerte zu verwenden, die ein falsches Format enthalten. Das Standardausgabeformat für Azure CLI ist JSON. Wenn Sie versuchen, eine ID für eine Azure-Ressource in einer Variablen zu speichern, müssen Sie angeben --output tsv. Ein Beispiel:

# 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'.

Verwenden Sie nun den tsv-Ausgabetyp.

# 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

Fehler: Argumente sind erforderlich oder werden erwartet

Dieser Fehler wird angezeigt, wenn ein Azure CLI-Befehl einen erforderlichen Parameter fehlt, oder es gibt einen typografischen Fehler, der dazu führt, dass die Azure CLI den Verweisbefehl falsch analysiert. Wenn Sie mit einem Skript arbeiten, erhalten Sie auch diesen Fehler, wenn eine oder mehrere Bedingungen erfüllt sind:

• Ein Zeilenfortsetzungszeichen fehlt oder ist falsch.
• Beim Arbeiten in der PowerShell-Skriptsprache ist auf der rechten Seite eines Zeilenfortsetzungszeichens ein nachgestelltes Leerzeichen vorhanden. PowerShell-Splatting wird nur mit Arrays und nicht mit Hashtabellen bei Azure CLI-Befehlen unterstützt.
• Ein Variablenname enthält ein Sonderzeichen, z. B. einen Gedankenstrich (-).

Fehler: Ressource nicht gefunden

Wenn die Azure CLI den Ressourcennamen oder die ID, die in einem Parameterwert übergeben wird, nicht finden kann, liegt dies in der Regel aus einem der folgenden Gründe:

• Der Ressourcenname oder die ID ist falsch geschrieben.
• Der Ressourcenname enthält Sonderzeichen und ist nicht von einfachen oder doppelten Anführungszeichen umgeben.
• Der Wert, der an eine Variable übergeben wird, hat unsichtbare führende oder nachfolgende Leerzeichen.
• Die Ressource ist vorhanden, befindet sich aber in einem anderen Abonnement.

Fehler: Fehler beim Parsen des Strings als JSON

Es gibt Unterschiede beim Zitieren zwischen Bash und PowerShell auf Linux sowie PowerShell auf Windows. Darüber hinaus können unterschiedliche Versionen von PowerShell unterschiedliche Ergebnisse erzielen. Bei komplexen Parametern, z. B. einer JSON-Zeichenfolge, empfiehlt es sich, die Konvention der @<file> Azure CLI zu verwenden, um die Interpretation der Shell zu umgehen. Weitere Informationen finden Sie in einem der folgenden Artikel:

Siehe Beispiele für die JSON-Syntax in Bash, PowerShell und cmd.exe, im Tutorial Quoting-Unterschiede zwischen Skriptsprachen – JSON-Zeichenfolgen.

Fehler: InvalidTemplateDeployment

Wenn Sie versuchen, eine Azure-Ressource an einem Speicherort zu erstellen, der diese Ressource nicht anbietet, erhalten Sie eine Fehlermeldung ähnlich der folgenden Meldung: "Die folgenden SKUs sind für Kapazitätseinschränkungen fehlgeschlagen: myDesiredSkuName" ist derzeit nicht am Speicherort "mySpecifiedLocation" verfügbar.

Hier ist ein vollständiges Fehlerbeispiel für eine virtuelle Maschine, die an westus nicht erstellt werden kann.

{"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."}]}}

Die Lösung besteht darin, eine Eigenschaft Ihrer angeforderten Azure-Ressource zu ändern oder einen anderen Speicherort zu versuchen.

Fehler: Abonnement nicht gefunden

Wenn Sie den Abonnementnamen oder die ID nicht falsch eingegeben haben, tritt dieser Fehler auf, wenn ein Ressourcenanbieter nicht im aktiven Abonnement registriert ist. Wenn Sie z. B. az storage account createausführen möchten, muss der Microsoft.Storage-Anbieter registriert sein. Informationen zum Registrieren eines Ressourcenanbieters finden Sie unter Azure-Ressourcenanbieter und -Typen.

Fehler: Fehler beim Überprüfen eines fehlerhaften Handshake-Zertifikats

Informationen zum Beheben dieses Fehlers finden Sie unter Arbeiten hinter einem Proxy-.

Arbeiten hinter einem Proxy

Wenn Sie Azure CLI über einen Proxyserver verwenden, der selbstsignierte Zertifikate nutzt, könnte die von der Azure CLI verwendete Python-Bibliothek möglicherweise den folgenden Fehler verursachen: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",). Um diesen Fehler zu beheben, legen Sie die Umgebungsvariable REQUESTS_CA_BUNDLE auf den Pfad der Zertifikatdatei der Zertifizierungsstelle im PEM-Format fest.

Fügen Sie das Zertifikat des Proxyservers zur Zertifikatsdatei des CA-Bündels hinzu, oder kopieren Sie den Inhalt in eine andere Zertifikatsdatei. Legen Sie dann REQUESTS_CA_BUNDLE auf den neuen Dateispeicherort fest. Ein Beispiel:

<Original cacert.pem>

-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----

Für einige Proxys ist eine Authentifizierung erforderlich. Das Format der HTTP_PROXY- oder HTTPS_PROXY Umgebungsvariablen sollte die Authentifizierung enthalten, z. B. HTTPS_PROXY="https://username:password@proxy-server:port". Ausführliche Informationen finden Sie unter Konfigurieren von Proxys für das Azure SDK für Python.

Dienstprinzipale

Informationen zur Problembehandlung von Dienstprinzipalen finden Sie in der Anleitung Bereinigung und Problembehandlung im Lernprogramm Arbeiten mit Dienstprinzipalen.

Andere Probleme

Wenn ein Produktproblem mit Azure CLI nicht in diesem Artikel aufgeführt ist, melden Sie ein Problem auf GitHub.

Siehe auch

• Tipps zur erfolgreichen Verwendung der Azure CLI