Edit

Test-AzSubDeployment

Validate whether an ARM or Bicep template would be accepted for a subscription-scope deployment, without deploying it.

Syntax

Default (Default)

Test-AzSubDeployment
    -Name <string>
    -Location <string>
    -Mode <string>
    [-TemplateUri <string>]
    [-TemplateFile <string>]
    [-TemplateSpecId <string>]
    [-TemplateObject <hashtable>]
    [-QueryString <string>]
    [-ParametersUri <string>]
    [-ParametersFile <string>]
    [-Parameter <string[]>]
    [-ValidationLevel <string>]
    [-SubscriptionId <string>]
    [-Profile <string>]
    [<CommonParameters>]

Aliases

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.

Test-AzSubDeployment -Name sub-infra-2026-06-18 -Location eastus -Mode Incremental -TemplateFile ./main.bicep -Parameter rgName=demo-rg, rgLocation=eastus

Validate a local template with a local parameters file

Test-AzSubDeployment -Name create-rg -Location eastus -Mode Incremental -TemplateFile ./create-rg.json -ParametersFile ./create-rg.parameters.json

Validate a remote template with a remote parameters file

Validate a template hosted at a URL as deployment sub-infra-2026-06-18.

Test-AzSubDeployment -Name sub-infra-2026-06-18 -Location eastus -Mode Incremental -TemplateUri https://contoso.blob.core.windows.net/templates/create-rg.json -ParametersUri https://contoso.blob.core.windows.net/templates/create-rg.parameters.json

Validate a template spec

Test-AzSubDeployment -Name sub-infra-spec -Location westus2 -Mode Incremental -TemplateSpecId /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Resources/templateSpecs/myTemplateSpec/versions/1.0

Parameters

-Location

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.

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:False
Value from remaining arguments:False

-Mode

The deployment mode, Incremental or Complete.

Parameter properties

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

Parameter sets

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

-Name

The deployment name to validate.

Parameter properties

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

Parameter sets

(All)
Position:Named
Mandatory:True
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. 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.

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 or *.bicepparam). A .bicepparam file names its own template through its using declaration, so no template parameter is needed alongside it.

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 parameters file (for example, a blob URL). Include any required SAS token in this URI; -QueryString does not modify it.

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 token or query string sent on the template link. Requires -TemplateUri. A leading ? or & is removed. This value is not added to -ParametersUri.

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

-SubscriptionId

The Azure subscription that owns the deployment. 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

An inline ARM template supplied as a hashtable, for example the result of Get-Content ./azuredeploy.json -Raw | ConvertFrom-Json -AsHashtable.

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 version to deploy (for example, /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Resources/templateSpecs/{name}/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 JSON 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

Deployment validation strictness. One of Template, Provider, or ProviderNoRbac. Use a stricter level to catch schema or parameter issues earlier.

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

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.

Outputs

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

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.