Edit

Test-AzResourceGroupDeployment

Validate whether an ARM or Bicep template would be accepted for a resource group deployment, without deploying it.

Syntax

Default (Default)

Test-AzResourceGroupDeployment
    -ResourceGroupName <string>
    [-Name <string>]
    [-TemplateUri <string>]
    [-TemplateFile <string>]
    [-TemplateSpecId <string>]
    [-TemplateObject <hashtable>]
    [-QueryString <string>]
    [-ParametersUri <string>]
    [-ParametersFile <string>]
    [-Mode <string>]
    [-Parameter <string[]>]
    [-RollbackOnError]
    [-RollbackToDeploymentName <string>]
    [-ValidationLevel <string>]
    [-SubscriptionId <string>]
    [-Profile <string>]
    [<CommonParameters>]

Description

Asks Azure Resource Manager whether an ARM/Bicep template is syntactically correct and would be accepted for deployment into an existing resource group, without creating or modifying any resources. The template is supplied either inline (-TemplateFile), via URL (-TemplateUri), or by referencing a template spec (-TemplateSpecId). Template parameters can be supplied via file, URI, query string, or as Name=Value pairs through -Parameter.

Validation answers a different question from New-AzResourceGroupDeploymentWhatIf: this cmdlet reports whether the template would be accepted, while what-if predicts the individual resource changes a valid template would produce. 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 template before deploying it

Validate main.bicep with parameter file main.parameters.json as deployment infra-prod-2026-06-18 against resource group myrg.

Test-AzResourceGroupDeployment -ResourceGroupName myrg -Name infra-prod-2026-06-18 -TemplateFile ./main.bicep -ParametersFile ./main.parameters.json -Mode Incremental

Validate a remote template with inline parameters

Validate a template hosted at a URL, overriding the location parameter inline.

Test-AzResourceGroupDeployment -ResourceGroupName myrg -Name infra-test -TemplateUri https://example.com/azuredeploy.json -Parameter location=eastus

Parameters

-Mode

Deployment mode used to evaluate the template. Use Incremental (default) to add and update resources, or Complete to also account for resources in the resource group that aren't declared in the template.

Parameter properties

Type:String
Accepted values:Incremental, Complete
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Name

The name of the deployment. Used to track and reference the validation in deployment history. When omitted, defaults to the template file or URI name without its extension, or a generated GUID when no valid name can be derived.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Parameter

Template parameters supplied as inline Name=Value pairs. Use this when you don't have a parameters file. Repeat the flag or pass an array for multiple values.

Parameter properties

Type:

String[]

Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersFile

Path to a local ARM/Bicep parameters file (*.parameters.json).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:TemplateParameterFile

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ParametersUri

URI of a remote ARM/Bicep parameters file (for example, a blob URL).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:TemplateParameterUri

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Profile

Name of a saved profile to use for this call instead of the currently-active one. Manage profiles with Set-AzProfile / Get-AzProfile.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-QueryString

Optional SAS or query string appended to -TemplateUri / -ParametersUri when those URIs require authentication.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResourceGroupName

The name of the resource group to validate the deployment against. The resource group must already exist.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-RollbackOnError

Record that the resource group should roll back to its last successful deployment if the deployment later fails. Mutually exclusive with -RollbackToDeploymentName.

Parameter properties

Type:SwitchParameter
Supports wildcards:False
DontShow:False
Aliases:RollbackToLastDeployment

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-RollbackToDeploymentName

Name of an explicit prior deployment to roll back to on failure. Mutually exclusive with -RollbackOnError.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False
Aliases:RollBackDeploymentName

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-SubscriptionId

The Azure subscription ID that owns the target resource group. Defaults to the active profile's subscription when omitted.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateFile

Path to a local ARM JSON or Bicep template file.

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateObject

A hash table which represents the template.

Parameter properties

Type:Hashtable
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateSpecId

Resource ID of an existing template spec to validate (for example, /subscriptions/.../providers/Microsoft.Resources/templateSpecs/<spec>/versions/<version>).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-TemplateUri

URI of a remote ARM/Bicep template (for example, a blob URL).

Parameter properties

Type:String
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ValidationLevel

Validation strictness. Template checks the template only, Provider (default) also calls resource providers, and ProviderNoRbac calls providers while skipping RBAC checks.

Parameter properties

Type:String
Accepted values:Template, Provider, ProviderNoRbac
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

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.

Inputs

String

You can pipe the ResourceGroupName, Mode, and RollbackToDeploymentName values to this cmdlet by property name.

Outputs

Microsoft.Azure.Azclips.Extensions.Resources.Models.DeploymentValidateResult

A DeploymentValidateResult describing the outcome of the validation, including the validated resources and 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 template that fails validation is reported as an error listing the validation failures, so a non-zero exit code means "the template would be rejected", not "the command malfunctioned". Use New-AzResourceGroupDeployment 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 (capture them with -ErrorVariable) instead of to the output stream as a list of PSResourceManagerError objects. The legacy parameter names -TemplateParameterFile, -TemplateParameterUri, -RollbackToLastDeployment, and -RollBackDeploymentName are accepted as aliases.