Azure agent troubleshooting

This topic details some common issues and frequently asked questions encountered in installing and configuring an agent on Azure.

Failed to create role assignments

If you see the following error:

Tenant ID, application ID, principal ID, and scope are not allowed to be updated.

This is caused by an Azure agent previously deployed to the same Azure resource group, which created role assignments that now need to be deleted. This error may occur even if the prior deployment failed, as the role assignments may have been created during the deployment attempt.

To resolve this issue:

Log in to the Azure Portal.
Use the search bar to search for "resource groups", and click the Resource groups result.
On the Resource groups screen, select the resource group you are using for the agent.
Click Access control (IAM).
You will see a role assignment entry for "Identity not found" associated with the following roles:
- AcrPull
- Key Vault Secrets Officer
- Storage Account Contributor
- Storage Blob Data Contributor
- Storage Blob Data Reader
All five of these orphaned role assignments need to be deleted. Click the role assignment's checkbox to select it, then click Remove at the top of the list.

Conflict when creating the key vault

If you see the following error:

A vault with the same name already exists in deleted state. You need to either recover or purge existing key vault. Follow this link https://go.microsoft.com/fwlink/?linkid=2149745 for more information on soft delete.

This is because a key vault with the same name existed before and has been deleted, or a key vault with the same name exists in another resource group.

You can specify a different name on the template deployment page, or, if it's a deleted vault, purge it.

The environment network configuration is invalid: The subnet and its addressPrefix could not be found

This may occur when deploying a Container App environment with the infrastructureSubnetId property set to an existing subnet reference with a /23 address size. The deployment will fail with the following error:

{
    "status": "Failed",
    "error": {
        "code": "ManagedEnvironmentInvalidNetworkConfiguration",
        "message": "The environment network configuration is invalid: The subnet and its addressPrefix could not be found."
    }
}

This occurs because Azure Container apps don't support virtual network subnets with addressPrefixes, only with addressPrefix.

To resolve this issue, you can recreate the subnet using the Azure command line interface (CLI), specifying an --address-prefix parameter.

The following command will create a suitable subnet in the Azure CLI:

az network vnet subnet create \
  --resource-group <resource-group-name> \
  --vnet-name <vnet-name> \
  --name <agent-name> \
  --address-prefix <address-prefix> \
  --service-endpoints Microsoft.Storage Microsoft.KeyVault

Substitute appropriate names for <resource-group-name>, <vnet-name>, <agent-name>, and <address-prefix>. The address prefix is a subnet identifier with the form 10.0.80.0/23.

Using the agent with a static IP address

The default installation process assumes a dynamic IP address. If you require a static public IP address, you will need to add a NAT gateway to the subnet. This will allow any resources deployed to the subnet to present the public IP address of the NAT gateway.

Using the agent with a proxy server

Some additional configuration is required to use the agent through a proxy server. For details, read Using a proxy server with the agent.

Container app environment already in use

If the template launch fails due to the chosen subnet already being in use by another container app environment, create a new subnet in the same VNet, following the documented requirements, and choose the new subnet at launch.