This cmdlet has the following aliases,
Test-AzSubscriptionDeployment
Description
Asks Azure Resource Manager whether a template is syntactically correct and would be accepted for deployment at the subscription scope, without creating or modifying any resources. The template is supplied as a local ARM JSON or Bicep file (-TemplateFile), a URL (-TemplateUri), a template spec (-TemplateSpecId), or an inline hashtable (-TemplateObject). Bicep files are compiled with the Bicep CLI, which must be installed. Template parameters can be supplied via file (-ParametersFile), URI (-ParametersUri), or as Name=Value pairs through -Parameter. -QueryString supplies a query string for the template URI, not template parameter values.
When the template is valid the validation result is returned; when it is not, the cmdlet writes the validation errors and terminates with a non-zero exit code.
Examples
Validate a Bicep file with inline parameters
Validate main.bicep as deployment sub-infra-2026-06-18, and supply its parameters inline.
The Azure region that stores the deployment metadata, for example eastus. Subscription-scope deployments have no resource group to inherit a region from, so a location is required.
Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Pass an array for multiple values. Values are parsed as JSON when possible, and otherwise treated as strings. Inline values overlay same-named keys from -ParametersFile and cannot be combined with -ParametersUri.
Path to a local ARM/Bicep parameters file (*.parameters.json or *.bicepparam). A .bicepparam file names its own template through its using declaration, so no template parameter is needed alongside it.
Optional SAS token or query string sent on the template link. Requires -TemplateUri.
A leading ? or & is removed. This value is not added to -ParametersUri.
Resource ID of an existing template spec version to deploy (for example, /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Resources/templateSpecs/{name}/versions/{version}).
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
about_CommonParameters.
A DeploymentValidateResult describing the outcome of the validation, including the deployment properties Azure Resource Manager resolved. No resources are created or modified.
Notes
Validation is read-only: it never creates or modifies resources. A non-zero exit code means the template would be rejected. Use New-AzSubDeployment to deploy once validation passes.
Differences from Az.Resources: on success this cmdlet returns the DeploymentValidateResult instead of no output, and validation failures are written to the error stream instead of the output stream. The legacy name Test-AzSubscriptionDeployment and the parameter names -DeploymentName, -TemplateParameterFile, and -TemplateParameterUri are accepted as aliases.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.