Problembehandlung für die Azure Developer CLI

  • Artikel

Dieser Artikel enthält Lösungen für häufige Probleme, die auftreten können, wenn Sie Azure Developer CLI (azd) verwenden.

Hilfe und Feedback

Wenn Sie in diesem Artikel nicht finden können, wonach Sie suchen oder Feedback geben möchten, können Sie Fragen zu Azure Developer CLI-Diskussionen posten.

Sie können Fehler auch melden, indem Sie GitHub-Probleme im GitHub-Repository der Azure Developer CLI öffnen.

Verwenden des Schalters --debug

Wenn beim Arbeiten mit azddem Befehl ein unerwartetes Problem auftritt, führen Sie den Befehl erneut aus --debug , um zusätzliche Debugging- und Diagnoseausgabe zu aktivieren.

azd up --debug

Sie können die Debugausgabe auch an eine lokale Textdatei senden, um die Benutzerfreundlichkeit zu verbessern. Mit diesem Ansatz können die Debuginformationen von anderen Überwachungssystemen aufgenommen werden und können auch bei der Einreichung eines Problems auf GitHub hilfreich sein.

Wichtig

Stellen Sie sicher, dass vertrauliche Informationen beim Übermitteln von Debugprotokollen auf GitHub oder beim Speichern in anderen Diagnose-Systemen redigiert werden.

azd deploy --debug > "<your-file-path>.txt"

Das .azure Verzeichnis

Azure Developer CLI geht davon aus, dass alle Verzeichnisse, die .azure im Verzeichnis gespeichert sind, Azure Developer CLI-Umgebungen sind. Führen Sie keine Azure Developer CLI-Befehle aus dem Startverzeichnis eines Benutzers aus, auf dem die Azure CLI installiert ist.

Nicht bei Azure angemeldet oder Token abgelaufen in Visual Studio

Nachdem Sie in Visual Studio ausgeführt azd init -t <template-name> haben, erhalten Sie die folgende Fehlermeldung: "Für den Zugriff auf Remote: dieses Repository müssen Sie die OAuth-App lizenzierung Visual Studioerneut autorisieren."

Lösung

Führen Sie die Ausführung aus azd auth login , um das Zugriffstoken zu aktualisieren.

Aktualisierte Azure-Kontoberechtigungen werden nicht aktualisiert in azd

Speichert standardmäßig azd Ihre Azure-Anmeldeinformationen und -berechtigungen zwischen. Wenn Ihrem Azure-Konto neue Rollen und Berechtigungen zugewiesen oder zusätzlichen Abonnements hinzugefügt werden, werden diese Änderungen möglicherweise nicht sofort angezeigt.azd Um dieses Problem zu azd beheben, melden Sie sich ab, und melden Sie sich dann mit den folgenden Befehlen wieder an:

azd auth logout

azd auth login

Folgen Sie den Anweisungen des azd auth login Befehls, um den Anmeldevorgang abzuschließen und Ihre zwischengespeicherten Anmeldeinformationen zu aktualisieren.

Cloud Shell-Einschränkungen für azd

Es gibt einige Einschränkungen für die Ausführung azd in Cloud Shell:

Docker-Unterstützung in Cloud Shell

Cloud Shell unterstützt nicht das Ausführen von Docker build oder run Befehlen, da der Docker-Daemon nicht ausgeführt wird. Weitere Informationen finden Sie unter "Problembehandlung bei Cloud Shell".

Cloud Shell-Timeout

Cloud Shell kann sich während einer langen Bereitstellung oder anderer lang ausgeführter Aufgaben zeitüberschreitungen. Stellen Sie sicher, dass die Sitzung nicht im Leerlauf ist. Siehe Cloud Shell-Nutzungsgrenzwerte.

Cloud Shell-Schnittstelle

Cloud Shell ist in erster Linie eine Befehlszeilenschnittstelle und verfügt über weniger Features als eine integrierte Entwicklungsumgebung wie Visual Studio Code.

Eine Verbindung mit dem Docker-Daemon in Cloud Shell kann nicht hergestellt werden.

Cloud Shell verwendet einen Container, um Ihre Shellumgebung zu hosten, sodass Aufgaben, die das Ausführen des Docker-Daemons erfordern, nicht zulässig sind.

Installieren einer anderen Version von azd in Cloud Shell

In einigen Fällen kann es erforderlich sein, eine andere Version azd als die version zu installieren, die bereits in Cloud Shell verwendet wird. Gehen Sie dazu in Bash wie folgt vor:

  1. Ausführen mkdir -p ~/bin , um sicherzustellen, dass der ~/bin Ordner vorhanden ist
  2. Führen Sie die Ausführung mkdir -p ~/azd aus, um sicherzustellen, dass ein lokaler ~/azd Ordner vorhanden ist.
  3. Run curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version> (<version> wäre stable standardmäßig, aber eine bestimmte veröffentlichte Version 1.0.0 kann auch angegeben werden).

Nach der Installation hat die symbolisch verknüpfte ~/bin Version azd Vorrang vor der symbolisch verknüpften Versionazd./usr/local/bin

So rückgängig machen Sie die Version der azd bereits installierten Cloud Shell in Bash verwenden:

  1. Ausführen von rm ~/bin/azd
  2. Ausführen von rm -rf ~/azd

Lösung

Verwenden Sie einen anderen Host, um Aufgaben auszuführen, die den Docker-Daemon erfordern. Eine Möglichkeit besteht darin, Docker-Computer zu verwenden, wie in der Dokumentation zur Problembehandlung in Cloud Shell beschrieben.

Azure Bicep CLI-Anforderung

azd up und azd provision erfordern die neueste Version von Azure Bicep CLI. Möglicherweise wird die folgende Fehlermeldung angezeigt: "Fehler: Fehler beim Kompilieren der Bicep-Vorlage: Fehler beim Ausführen des Az PowerShell-Modul-Bicep-Builds: Exit code: 1, stdout: , stderr: WARNING: Eine neue Bicep-Version ist verfügbar: v0.4.1272."

Lösung

Zuvor war Bicep eine Preqrequisite für die Installation und Verwendung azd . azd installiert Bicep jetzt automatisch im lokalen azd Bereich (nicht global) und dieses Problem sollte jetzt behoben werden. Wenn Sie jedoch eine andere Version verwenden möchten, können Sie die Umgebungsvariable festlegen: AZD_BICEP_TOOL_PATH Zeigen Sie auf den Speicherort der benötigten Version.

azd up oder azd provision schlägt fehl

Dinge können manchmal verwischte oder azd upazd provision. Häufige Fehler sind z.B. folgende:

  • "Bestimmte Ressourcen in einer Azure-Region können nicht bereitgestellt werden, da die Region nicht mehr in der Kapazität ist."
  • "Relevanter Ressourcenanbieter ist in dieser Region nicht vorhanden."

Die Schritte zur Problembehandlung können je nach Ursache unterschiedlich sein.

Lösung

  1. Öffnen Sie das Azure-Portal.

  2. Suchen Sie Ihre Ressourcengruppe, die rg-your-environment-name<> ist.

  3. Wählen Sie "Bereitstellungen" aus, um weitere Informationen zu erhalten.

  4. Stellen Sie sicher, dass Sie einen Umgebungsnamen angegeben haben, der dem Namen Ihrer Umgebung entspricht.

  5. Wechseln Sie zu https://github.com/<your repo>/actions, und verweisen Sie dann auf die Protokolldatei in der Pipeline, um weitere Informationen zu erhalten.

Weitere Ressourcen finden Sie unter Problembehandlung allgemeiner Azure-Bereitstellungsfehler – Azure Resource Manager.

azd init erfordert sudo.

azd Erstellen Sie vorher azd version = azure-dev-cli_0.2.0-beta.1einen .azd Ordner mit drw-r--r-- Zugriff.

Dies führt zu einem Problem, da die Verwendung dieser oder einer früheren Version auf einem Linux-Setup (WSL, ssh-remote, devcontainer usw.) bereits einen .azd Ordner mit schreibgeschütztem Modus bereitstellt.

Lösung

  1. Löschen Sie den bereits bereitgestellten .azd Ordner manuell:

    rm -r ~/.azd

  2. azd Führen Sie diese Schritte azd init aus, um den Ordner erneut mit den richtigen Zugriffsebenen zu erstellen.

azd monitor für Entwicklungscontainer

azd monitor wird derzeit nicht unterstützt, wenn Sie einen Entwicklungscontainer als Entwicklungsumgebung verwenden.

Authentifizierung in Codespaces-Umgebungen nicht möglich

Wenn Authentifizierungsprobleme in Codespaces auftreten, stellen Sie sicher, dass die Vorlage Dockerfile die sudo apt-get update && sudo apt-get install xdg-utils Befehle enthält. Der xdg-utils Befehl öffnet eine Browserregisterkarte, über die Sie sich anmelden können.

Statische Web-Apps trotz Erfolgsmeldung nicht bereitgestellt werden

Ein bekanntes Problem ist beim Bereitstellen in Azure Static Web-Apps vorhanden, in dem die Standardausgabe azd up möglicherweise den Erfolg der Aktion anzeigt, aber die Änderungen wurden nicht tatsächlich bereitgestellt. Sie können dieses Problem diagnostizieren, indem Sie den azd up Befehl mit aktivierter --debug Kennzeichnung ausführen. In den Ausgabeprotokollen wird möglicherweise die folgende Meldung angezeigt:

Preparing deployment. Please wait...
An unknown exception has occurred

Dieses Problem tritt wahrscheinlich auf, wenn azd sie von einer GitHub-Aktion ausgeführt wird. Als Problemumgehung kopieren staticwebapp.config.json Sie nach dem Erstellen Ihrer Website in den Buildordner. Sie können diesen Schritt automatisieren, indem Sie einen Prepackage- oder Predeploy-Befehlshaken verwenden, mit dem Sie benutzerdefinierte Skripts an verschiedenen Stellen in den azd-Befehlsworkflows ausführen können.

Das Produktteam arbeitet daran, dieses Problem zu beheben.

Fehler "GitHub-Aktionen" – "Verfügt nicht über geheime Schlüssel zum Abrufen der Berechtigung für den Schlüsseltresor"

Die Gemeinsame Nutzung desselben Umgebungs- oder Ressourcengruppennamens beim lokalen Bereitstellen von Ressourcen und in GitHub-Aktionen kann den Fehler Does not have secrets get permission on key vault.. vom Key Vault-Dienst erzeugen. Key Vault unterstützt keine inkrementellen Berechtigungsupdates über Bicep, was bedeutet, dass der GitHub-Aktionen-Workflow die Zugriffsrichtlinienberechtigungen des lokalen Benutzers überschreibt.

Die empfohlene Lösung für dieses Problem besteht darin, separate Umgebungsnamen für lokale Entwicklungs- und GitHub-Aktionen-Workflows zu verwenden. Weitere Informationen zur Verwendung mehrerer Umgebungen mit dem azd env Befehl auf der Faq-Seite.

Textbasierte Browserunterstützung

Textbasierte Browser werden derzeit nicht von azd monitor.

azd pipeline config Verwenden von AzDo für Java-Vorlagen unter Windows

Möglicherweise tritt bei der Ausführung azd pipeline config mit AzDo für Java-Vorlagen unter Windows ein Fehler auf. Sie haben beispielsweise Folgendes:

  1. Führen Sie folgendes unter Windows aus:

    azd init --template Azure-Samples/todo-java-mongo
azd pipeline config

  2. Der folgende Fehler wurde empfangen:

    Screenshot showing the error received when running azd pipeline config with AzDo for Java on Windows.

Lösung

Dies ist ein bekanntes Problem. Führen Sie während der Behebung dieses Problems den folgenden Befehl aus:

git update-index --chmod=+x src/api/mvnw && git commit -m "Fix executable bit permissions" && git push

failed packaging service 'api': failed invoking action 'package', failed to run NPM script build, signal: segmentation fault Fehler nach dem Upgrade azd auf Apple Silicon (M1/M2)

In einigen Situationen kann das Upgrade von der x86_64-Version azd auf eine ARM64-Binärdatei zu Fehlern für Vorlagen führen, die mit der x86_64 Version von azd. Dies liegt daran, dass die Vorlage eine Version verwendet, deren v8-compile-cache Bytecode unter x86_64 in einen ARM64-Prozess geladen werden kann.

Aktualisieren Sie das Paket im betroffenen Projekt, um dieses v8-compile-cache Problem zu beheben:

  1. Ändern des Verzeichnisses in den Dienst, der fehlgeschlagen ist (src/api im Fall von failed packaging service 'api')
  2. Ausführen von npm upgrade v8-compile-cache
  3. Ändern Sie das Verzeichnis in das Stammverzeichnis des Repositorys, und führen Sie den azd Befehl (z. B. oder azd up) erneut aus. azd package

azd pipeline config Fehler aufgrund der Richtlinie für bedingten Zugriff

Wenn Sie ausgeführt werden azd pipeline config, erhalten Sie möglicherweise eine Fehlermeldung wie die folgenden:

ERROR: failed to create or update service principal: failed retrieving application list, failed executing request: http call(https://login.microsoftonline.com/common/oauth2/v2.0/token)(POST) error: reply status code was 400:
{"error":"invalid_grant","error_description":"AADSTS50005: User tried to log in to a device from a platform (Unknown) that's currently not supported through Conditional Access policy. Supported device platforms are: iOS, Android, Mac, and Windows flavors.\r\nTrace ID: be3438c1-42fc-4c37-96d8-0e723ac54f01\r\nCorrelation ID: f535565f-9f3c-4014-ad65-403f514bf892\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"be3438c1-42fc-4c37-96d8-0e723ac54f01","correlation_id":"f535565f-9f3c-4014-ad65-403f514bf892"}

Dieser Fehler bezieht sich auf die Microsoft Entra-Mandantenaktivierung von Richtlinien für bedingten Zugriff. Die spezifische Richtlinie erfordert, dass Sie bei einer unterstützten Geräteplattform angemeldet sind.

Möglicherweise erhalten Sie diesen Fehler auch aufgrund der Anmeldung mithilfe des Gerätecodemechanismus, wodurch verhindert wird, dass Microsoft Entra-ID Ihre Geräteplattform ordnungsgemäß erkennt.

Lösung

Zum Konfigurieren des Workflows müssen Sie GitHub die Berechtigung erteilen, Azure in Ihrem Namen bereitzustellen. Autorisieren Sie GitHub, indem Sie einen Azure-Dienstprinzipal erstellen, der in einem GitHub-Geheimnis mit dem Namen gespeichert ist AZURE_CREDENTIALS. Wählen Sie Ihren Codespace-Host für Schritte aus:

  1. Stellen Sie sicher, dass Sie auf einem gerät ausgeführt werden, das gemäß der Fehlermeldung als unterstützt aufgeführt ist.

  2. Führen Sie den Erneuten Ausführen azd auth login mit der angefügten Kennzeichnung --use-device-code=false aus:

    azd auth login --use-device-code=false

  3. Nach der Anmeldung wird möglicherweise eine Fehlermeldung mit der Meldung localhost refused to connect angezeigt. Wenn ja:

    1. Kopieren Sie die URL.
    2. Führen Sie curl '<pasted url>' (URL in Anführungszeichen) in einem neuen Codespaces-Terminal aus.

    Im ursprünglichen Terminal sollte die Anmeldung nun erfolgreich sein.

  4. Führen Sie nach der Anmeldung erneut aus azd pipeline config.