> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting a Maia runner hosted on Azure

export const m_runner = "Maia runner";

export const maia = "Maia";

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["Azure"]} />

This topic details some common issues and frequently asked questions encountered in installing and configuring a {m_runner} on Azure.

***

## Failed to create role assignments

Each {m_runner} needs to be deployed into a different resource group. If you deploy a {m_runner} into a resource group where a {m_runner} already exists, role assignment creation will fail for the new {m_runner}.

If you are deploying a new {m_runner} into a resource group where a {m_runner} deployment previously failed, you may see the following error:

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

This indicates that role assignments may have been created during the failed deployment attempt, and the continued existence of these orphaned role assignments has caused the failure of the new {m_runner} deployment.

To resolve this issue, you need to delete the old role assignments:

1. Log in to the [Azure Portal](https://portal.azure.com/#home).

2. Use the search bar to search for "resource groups", and click the **Resource groups** result.

3. On the **Resource groups** screen, select the resource group you are using for the {m_runner}.

4. Click **Access control (IAM)**.

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

6. 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 a subnet that doesn't use the `addressPrefix` attribute. 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 <YourResourceGroup> \
  --vnet-name <YourVNetName> \
  --name <YourPrivateSubnetName> \
  --address-prefix <StartingIP>/27 \
  --service-endpoints Microsoft.Storage Microsoft.KeyVault \
  --delegations Microsoft.App/environments
```

***

## Using the Maia runner 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 Maia runner with a proxy server

Some additional configuration is required to use the {m_runner} through a proxy server. For details, read [Using a proxy server with the {m_runner}](/docs/guides/customizing-runner-networking-and-connectivity).

***

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