Troubleshoot Azure Developer CLI
This article provides solutions to common problems that might arise when you're using Azure Developer CLI (azd).
Get help and give feedback
If you're unable to find what you're looking for in this article or you want to provide feedback, you can post questions to Azure Developer CLI Discussions.
You can also report bugs by opening GitHub Issues in the Azure Developer CLI GitHub repository.
Using the --debug
switch
If you encounter an unexpected issue while working with azd
, rerun the command with the --debug
switch to enable additional debugging and diagnostic output.
azd up --debug
You can also send the debugging output to a local text file for improved usability. This approach allows the debugging info to be ingested by other monitoring systems and can also be useful when filing an issue on GitHub.
Important
Make sure to redact any sensitive information when submitting debug logs on GitHub or saving them to other diagnostics systems.
azd deploy --debug > "<your-file-path>.txt"
The .azure
directory
Azure Developer CLI assumes that any directories that are stored in the .azure
directory are Azure Developer CLI environments. Don't run Azure Developer CLI commands from the home directory of a user that has the Azure CLI installed.
Not logged in to Azure or token expired in Visual Studio
After you've run azd init -t <template-name>
in Visual Studio, you get the following error: "To access remote: this repository, you must reauthorize the OAuth Application Visual Studio
."
Solution
Run azd auth login
to refresh the access token.
Updated Azure account permissions do not refresh in azd
By default, azd
caches your Azure credentials and permissions. If your Azure account is assigned new roles and permissions, or is added to additional subscriptions, these changes may not be immediately reflected in azd
. To solve this issue, log out and then log back in to azd
using the following commands:
azd auth logout
azd auth login
Follow the prompts from the azd auth login
command to complete the sign-in process and update your cached credentials.
Cloud Shell limitations for azd
There are some limitations to running azd
in Cloud Shell:
Docker support in Cloud Shell
Cloud Shell does not support running docker build
or run
commands because the docker daemon is not running. For more information, see Cloud Shell Troubleshooting.
Cloud Shell timeout
Cloud Shell may time out during a long deployment or other long-running tasks. Make sure the session does not become idle. See Cloud Shell Usage limits.
Cloud Shell interface
Cloud Shell is primarily a command-line interface and will have fewer features than an integrated development environment like Visual Studio Code.
Cannot connect to the Docker daemon in Cloud Shell
Cloud Shell uses a container to host your shell environment, so tasks that require running the Docker daemon aren't allowed.
Install different version of azd in Cloud Shell
In some cases it may be necessary to install a different version of azd
than the version already in use in Cloud Shell. To do this in bash:
- Run
mkdir -p ~/bin
to ensure that the~/bin
folder is present - Run
mkdir -p ~/azd
to ensure that a local~/azd
folder is present - Run
curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --install-folder ~/azd --symlink-folder ~/bin --version <version>
(<version>
would bestable
by default but a specific released version like1.0.0
can also be specified).
Once installed, the version of azd
symbolically linked in ~/bin
will take precedence over the
version of azd
symbolically linked in /usr/local/bin
.
To revert to using the version of azd
already installed on Cloud Shell in bash:
- Run
rm ~/bin/azd
- Run
rm -rf ~/azd
Solution
Use another host to perform tasks that require the docker daemon. One option is to use docker-machine, as described in the Cloud Shell troubleshooting documentation.
Azure Bicep CLI requirement
azd up
and azd provision
require the latest release of Azure Bicep CLI. You might get the following error message: "Error: failed to compile bicep template: failed running Az PowerShell module bicep build: exit code: 1, stdout: , stderr: WARNING: A new Bicep release is available: v0.4.1272."
Solution
Previously, Bicep was a preqrequisite for installing and using azd
. azd
now automatically installs Bicep within the local azd
scope (not globally) and this issue should now be resolved. However, if you want to use a different version, you can set the environment variable: AZD_BICEP_TOOL_PATH
to point to the location of the version you need.
azd up
or azd provision
fails
Things can sometimes go awry with azd up
or azd provision
. Common errors include:
- "Can't provision certain resources in an Azure region because the region is out of capacity."
- "Relevant resource provider isn't present in that region."
The troubleshooting steps might differ, depending on the root cause.
Solution
Go to the Azure portal.
Locate your resource group, which is rg-<your-environment-name>.
Select Deployments to get more information.
Verify that you've specified an environment name that's the same as your environment name.
Go to
https://github.com/<your repo>/actions
, and then refer to the log file in the pipeline run for more information.
For other resources, see Troubleshoot common Azure deployment errors - Azure Resource Manager.
azd init
requires sudo
Before azd version = azure-dev-cli_0.2.0-beta.1
, azd
would create an .azd
folder with drw-r--r--
access.
This will cause an issue, as using this or any prior version on any Linux set-up (WSL, ssh-remote, devcontainer, etc.) already provides an .azd
folder with read-only mode.
Solution
Manually delete the already provided
.azd
folder:rm -r ~/.azd
Run
azd init
forazd
to create the folder again with the right access levels.
azd monitor
for development container
azd monitor
is currently not supported if you use a development container as your development environment.
Unable to authenticate in Codespaces environments
If you are experiencing authentication issues in Codespaces, make sure the template Dockerfile includes the sudo apt-get update && sudo apt-get install xdg-utils
commands. The xdg-utils
command will open a browser tab that allows you to sign-in.
Static Web Apps fail to deploy despite success message
A known issue exists when deploying to Azure Static Web Apps in which the default azd up
output may state the action was successful, but the changes were not actually deployed. You can diagnose this problem by running the azd up
command with the --debug
flag enabled. In the output logs you may see the following message:
Preparing deployment. Please wait...
An unknown exception has occurred
You are most likely to encounter this issue when azd
is run from a GitHub action. As a workaround, after you build your site, copy staticwebapp.config.json
into the build folder. You can automate this step this by using a prepackage or predeploy command hook, which allows you to execute custom scripts at various points in the azd command workflows.
The product team is working to resolve this issue.
GitHub Actions error - "Does not have secrets get permission on key vault"
Sharing the same environment or resource group name when provisioning resources locally and in GitHub Actions can produce the error Does not have secrets get permission on key vault..
from the Key Vault service. Key Vault does not support incremental permissions updates through Bicep, which effectively means the GitHub Actions workflow overwrites the Access Policy permissions of the local user.
The recommended solution to this issue is to use separate environment names for local development and GitHub Actions workflows. Read more about using multiple environments with the azd env
command on the FAQ page.
Text-based browser support
Text-based browsers are currently not supported by azd monitor
.
azd pipeline config
using AzDo for Java templates on Windows
You may encounter a failure when running azd pipeline config
with AzDo for Java templates on Windows. For example, you've:
Run the following on Windows:
azd init --template Azure-Samples/todo-java-mongo azd pipeline config
Received the following error:
Solution
This is a known issue. While we address this issue, try the following command:
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
failure after upgrading azd
on Apple Silicon (M1/M2)
In some situations, upgrading from the x86_64 version of azd
to an ARM64 binary may result in failures for templates
which have been built with the x86_64 version of azd
. This is because the template uses a version of
v8-compile-cache
which may try to load bytecode built under x86_64 into an ARM64 process.
To fix this issue, upgrade the v8-compile-cache
package in the affected project:
- Change directory to the service which failed (
src/api
in the case offailed packaging service 'api'
) - Run
npm upgrade v8-compile-cache
- Change directory to the root of the repo and run the
azd
command (e.g.azd package
orazd up
) again
azd pipeline config
failure due to Conditional Access Policy
When running azd pipeline config
, you may receive an error like the following:
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2022-12-16 21:10:37Z","error_codes":[50005],"timestamp":"2022-12-16 21:10:37Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd"}
This error is related to your Microsoft Entra tenant enablement of Conditional Access Policies. The specific policy requires that you are signed in into a supported device platform.
You may also be receiving this error due to being logged in using the device code mechanism, which prevents Microsoft Entra ID from detecting your device platform correctly.
Solution
To configure the workflow, you need to give GitHub permission to deploy to Azure on your behalf. Authorize GitHub by creating an Azure Service Principal stored in a GitHub secret named AZURE_CREDENTIALS
. Select your Codespace host for steps:
Make sure you're running on a device listed as supported, per the error message.
Rerun
azd auth login
with the flag--use-device-code=false
appended:azd auth login --use-device-code=false
You may receive an error with message
localhost refused to connect
after logging in. If so:- Copy the URL.
- Run
curl '<pasted url>'
(URL in quotes) in a new Codespaces terminal.
In the original terminal, the login should now succeed.
After logging in, rerun
azd pipeline config
.