|
| 1 | +--- |
| 2 | +title: 'Preflight: Server-side validation before deployment' |
| 3 | +description: Server‑side validation phase that runs after the template is submitted but before any resources are created or modified. |
| 4 | +ms.topic: article |
| 5 | +ms.date: 04/09/2026 |
| 6 | +--- |
| 7 | + |
| 8 | +# Preflight: Server validation before deployment |
| 9 | + |
| 10 | +In Azure Resource Manager (ARM), server-side validation consists of two distinct parts: |
| 11 | + |
| 12 | +- Static validation, which is the operation developers interact with. |
| 13 | +- Resource provider preflight validation, which is the internal resource provider validation phase. |
| 14 | + |
| 15 | +Static validation checks aspects of the template that ARM can evaluate without calling resource providers, such as: |
| 16 | + |
| 17 | +- Template structure and schema correctness |
| 18 | +- Parameter definitions and basic value constraints |
| 19 | +- Expression evaluation and template consistency |
| 20 | + |
| 21 | +These checks ensure the template is syntactically and structurally valid before deeper validation occurs. |
| 22 | + |
| 23 | +Preflight validation is an Azure Resource Manager (ARM) internal process executed during the validation phase. Its purpose is to accelerate error detection by preventing deployments that are known to fail. During this step, ARM invokes the relevant resource providers to verify that the deployment is feasible, without creating or modifying any resources. This part validates: |
| 24 | + |
| 25 | +- **Resource name conflicts**: During preflight, ARM evaluates the final, resolved resource names and checks whether they violate provider‑enforced uniqueness or naming rules. This check happens after expressions like `concat()` or `uniqueString()` are resolved. Preflight validation commonly fails when: |
| 26 | + |
| 27 | + - A globally unique name (for example, a storage account name) is already taken |
| 28 | + - A resource name violates provider‑specific naming constraints |
| 29 | + |
| 30 | +- **Scope correctness**: Preflight validation ensures that resources are being deployed to a valid scope and that the deployment command matches the resource types declared in the template. This validation includes: |
| 31 | + |
| 32 | + - Whether the deployment scope (resource group, subscription, management group, tenant) is compatible with the resource types |
| 33 | + - Whether required parent scopes exist. For example, deploying a resource group–scoped resource at subscription scope without a resource group. |
| 34 | + |
| 35 | +- RBAC permissions (whether you can deploy those resource types): During preflight, ARM verifies that the caller has sufficient permissions at the deployment scope to create or modify the requested resources. If the identity lacks permissions, the deployment is rejected before execution. Typical preflight permission failures include: |
| 36 | + |
| 37 | + - Missing write permissions for a resource type |
| 38 | + - Insufficient permissions at the target scope |
| 39 | + - Required resource providers not registered |
| 40 | + |
| 41 | +- Basic provider and API compatibility: Preflight validation confirms that: |
| 42 | + |
| 43 | + - The referenced resource providers are registered |
| 44 | + - The specified API versions are valid and supported |
| 45 | + - The resource type is recognized by Azure Resource Manager |
| 46 | + |
| 47 | + If a provider isn't registered or the API version is invalid, ARM fails the deployment during preflight. |
| 48 | + |
| 49 | +If any of these checks fail, the deployment never starts. |
| 50 | + |
| 51 | +## Limitations |
| 52 | + |
| 53 | +Preflight validation is a best-effort process and does not catch all deployment-time errors. It cannot detect runtime failures (for example, errors within a custom script extension during execution), and its validation may be incomplete when resources depend on values that are not yet available, such as dynamically generated properties from other resources. |
| 54 | + |
| 55 | +## Run preflight |
| 56 | + |
| 57 | +Preflight validation runs automatically when you use deployment validate or what-if style commands. For example, these operations run preflight validation: |
| 58 | + |
| 59 | +- ARM JSON or Bicep validation in Azure CLI or PowerShell |
| 60 | + |
| 61 | + ### [Azure CLI](#tab/azure-cli) |
| 62 | + |
| 63 | + ```azurecli |
| 64 | + az deployment group validate \ |
| 65 | + --resource-group myResourceGroup \ |
| 66 | + --template-file main.bicep |
| 67 | + ``` |
| 68 | + |
| 69 | + ### [PowerShell](#tab/azure-powershell) |
| 70 | + |
| 71 | + ```azurepowershell |
| 72 | + Test-AzResourceGroupDeployment ` |
| 73 | + -ResourceGroupName myResourceGroup ` |
| 74 | + -TemplateFile ./main.bicep |
| 75 | + ``` |
| 76 | + |
| 77 | + For more information, see [Deploy Bicep files with the Azure CLI](./deploy-cli.md) and [Deploy Bicep files with the Azure PowerShell](./deploy-powershell.md). |
| 78 | + |
| 79 | +- Azure portal **Review + create** step |
| 80 | + |
| 81 | + Currently, the Azure portal only supports deploying ARM JSON templates. For more information, see [Deploy ARM templates with the Azure portal](../templates/deploy-portal.md). |
| 82 | + |
| 83 | +- What-if |
| 84 | + |
| 85 | + What-if includes preflight checks before calculating changes unless you configure it to skip the preflight. For more information, see [Running the what-if operation](./deploy-what-if.md#running-the-what-if-operation). |
| 86 | + |
| 87 | +Preflight errors appear in the activity log but not in deployment history, because the deployment never began. |
| 88 | + |
| 89 | +## Next steps |
| 90 | + |
| 91 | +- To use the what-if operation, see [Bicep What-If: Preview Changes Before Deployment](./deploy-what-if.md). |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments