排查使用 Azure Resource Manager 时的常见 Azure 部署错误Troubleshoot common Azure deployment errors with Azure Resource Manager

本文介绍了一些常见的 Azure 部署错误,并提供了有关如何解决这些错误的信息。This article describes some common Azure deployment errors, and provides information to resolve the errors. 如果找不到部署错误的错误代码,请参阅查找错误代码If you can't find the error code for your deployment error, see Find error code.

如果需要某个错误代码的信息,而本文没有提供该信息,请告知我们。If you're looking for information about an error code and that information isn't provided in this article, let us know.


本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

错误代码Error codes

错误代码Error code 缓解措施Mitigation 详细信息More information
AccountNameInvalidAccountNameInvalid 遵循存储帐户的命名限制。Follow naming restrictions for storage accounts. 解析存储帐户名称Resolve storage account name
AccountPropertyCannotBeSetAccountPropertyCannotBeSet 查看可用的存储帐户属性。Check available storage account properties. storageAccountsstorageAccounts
AllocationFailedAllocationFailed 群集或区域没有可用的资源或无法支持所请求的 VM 大小。The cluster or region doesn't have resources available or can't support the requested VM size. 稍后重试请求,或者请求不同的 VM 大小。Retry the request at a later time, or request a different VM size. Linux 预配和分配问题Windows 预配和分配问题排查分配失败问题Provisioning and allocation issues for Linux, Provisioning and allocation issues for Windows and Troubleshoot allocation failures
AnotherOperationInProgressAnotherOperationInProgress  等待并发操作完成。Wait for concurrent operation to complete.
AuthorizationFailedAuthorizationFailed  帐户或服务主体没有足够的访问权限,无法完成部署。Your account or service principal doesn't have sufficient access to complete the deployment. 请检查帐户所属的角色,及其与部署范围相对应的访问权限。Check the role your account belongs to, and its access for the deployment scope.

所需的资源提供程序未注册时,可能会收到此错误。You might receive this error when a required resource provider isn't registered.
Azure 基于角色的访问控制Azure Role-Based Access Control

解决注册问题Resolve registration
BadRequestBadRequest  发送的部署值与资源管理器预期的值不匹配。You sent deployment values that don't match what is expected by Resource Manager. 请检查内部状态消息,获取故障排除帮助。Check the inner status message for help with troubleshooting. 支持的位置Supported locations
冲突Conflict  在资源的当前状态下不允许所请求的操作。You're requesting an operation that isn't allowed in the resource's current state. 例如,仅当创建 VM 或该 VM 已取消分配时,才允许磁盘重设大小。For example, disk resizing is allowed only when creating a VM or when the VM is deallocated.
DeploymentActiveAndUneditableDeploymentActiveAndUneditable 等待目标为此资源组的并发部署完成。Wait for concurrent deployment to this resource group to complete.
DeploymentFailedCleanUpDeploymentFailedCleanUp 在完整模式下部署时,模板中不存在的任何资源都将被删除。When you deploy in complete mode, any resources that aren't in the template are deleted. 当没有足够的权限删除模板中所有不存在的资源时,会出现此错误。You get this error when you don't have adequate permissions to delete all of the resources not in the template. 若要避免此错误,请将部署模式更改为“增量”。To avoid the error, change the deployment mode to incremental. Azure 资源管理器部署模式Azure Resource Manager deployment modes
DeploymentNameInvalidCharactersDeploymentNameInvalidCharacters 部署名称只能包含字母、数字、"-"、"." 或 ""。The deployment name can only contain letter, digit, '-', '.' or ''.
DeploymentNameLengthLimitExceededDeploymentNameLengthLimitExceeded 部署名称限制为 64 个字符。The deployment names are limited to 64 characters.
DeploymentFailedDeploymentFailed DeploymentFailed 错误为常规错误,未提供解决错误所需的详细信息。The DeploymentFailed error is a general error that doesn't provide the details you need to solve the error. 请查看错误代码的错误详情,其中提供了详细信息。Look in the error details for an error code that provides more information. 查找错误代码Find error code
DeploymentQuotaExceededDeploymentQuotaExceeded 如果达到每个资源组的部署数限制 800,则会从历史记录中删除不再需要的部署。If you reach the limit of 800 deployments per resource group, delete deployments from the history that are no longer needed. 解决部署计数超出 800 的错误Resolve error when deployment count exceeds 800
DnsRecordInUseDnsRecordInUse  DNS 记录名称必须唯一。The DNS record name must be unique. 输入不同的名称。Enter a different name.
ImageNotFoundImageNotFound  检查 VM 映像设置。Check VM image settings.
InUseSubnetCannotBeDeletedInUseSubnetCannotBeDeleted  如果尝试更新资源,但已通过删除并创建资源处理了请求,则可能会出现此错误。You might get this error when trying to update a resource, and the request is processed by deleting and creating the resource. 请确保指定所有未更改的值。Make sure to specify all unchanged values. 更新资源Update resource
InvalidAuthenticationTokenTenantInvalidAuthenticationTokenTenant  获取相应租户的访问令牌。Get access token for the appropriate tenant. 只能从帐户所属的租户获取该令牌。You can only get the token from the tenant that your account belongs to.
InvalidContentLinkInvalidContentLink  很可能尝试过链接到不可用的嵌套模板。You've most likely attempted to link to a nested template that isn't available. 请仔细检查提供给嵌套模板的 URI。Double check the URI you provided for the nested template. 如果模板在存储帐户中存在,请确保 URI 可访问。If the template exists in a storage account, make sure the URI is accessible. 可能需要传递 SAS 令牌。You might need to pass a SAS token. 目前,无法链接到位于 Azure 存储防火墙后面的存储帐户中的模板。Currently, you can't link to a template that is in a storage account behind an Azure Storage firewall. 考虑将模板移到其他存储库,如 GitHub。Consider moving your template to another repository, like GitHub. 链接的模板Linked templates
InvalidDeploymentLocationInvalidDeploymentLocation 在订阅级别部署时,你为以前使用的部署名称提供了不同的位置。When deploying at the subscription level, you've provided a different location for a previously used deployment name. 订阅级别部署Subscription level deployments
InvalidParameterInvalidParameter  为资源提供的某个值与预期值不匹配。One of the values you provided for a resource doesn't match the expected value. 许多不同的条件可能会导致此错误。This error can result from many different conditions. 例如,密码可能不符合要求,或者 blob 名称可能不正确。For example, a password may be insufficient, or a blob name may be incorrect. 错误消息应表明哪个值需要更正。The error message should indicate which value needs to be corrected.
InvalidRequestContentInvalidRequestContent  部署值包含无法识别的值,或者缺少必需的值。The deployment values either include values that aren't recognized, or required values are missing. 确认资源类型的值。Confirm the values for your resource type.
InvalidRequestFormatInvalidRequestFormat  在运行部署时启用调试日志记录功能,并验证请求的内容。Enable debug logging when running the deployment, and verify the contents of the request. 调试日志记录Debug logging
InvalidResourceNamespaceInvalidResourceNamespace  检查在 type 属性中指定的资源命名空间。Check the resource namespace you specified in the type property.
InvalidResourceReferenceInvalidResourceReference  资源尚不存在,或错误地引用了它。The resource either doesn't yet exist or is incorrectly referenced. 请检查是否需要添加依赖项,Check whether you need to add a dependency. 并验证所使用的 reference 函数是否包括方案所需的参数。Verify that your use of the reference function includes the required parameters for your scenario. 解决依赖项问题Resolve dependencies
InvalidResourceTypeInvalidResourceType  检查在 type 属性中指定的资源类型。Check the resource type you specified in the type property.
InvalidSubscriptionRegistrationStateInvalidSubscriptionRegistrationState  向资源提供程序注册订阅。Register your subscription with the resource provider. 解决注册问题Resolve registration
InvalidTemplateInvalidTemplate  检查模板语法是否存在错误。Check your template syntax for errors. 解决模板无效的问题Resolve invalid template
InvalidTemplateCircularDependencyInvalidTemplateCircularDependency 删除不必要的依赖项。Remove unnecessary dependencies. 解决循环依赖项Resolve circular dependencies
LinkedAuthorizationFailedLinkedAuthorizationFailed  检查帐户所属的租户是否与要部署到的资源组所属的租户相同。Check if your account belongs to the same tenant as the resource group that you're deploying to.
LinkedInvalidPropertyIdLinkedInvalidPropertyId  无法正确解析资源的资源 ID。The resource ID for a resource isn't resolving correctly. 请检查是否提供了资源 ID 的所有必需值,包括订阅 ID、资源组名称、资源类型、父资源名称(如果需要)、资源名称。Check that you provide all required values for the resource ID, including subscription ID, resource group name, resource type, parent resource name (if needed), and resource name.
LocationRequiredLocationRequired  提供资源的位置。Provide a location for the resource. 设置位置Set location
MismatchingResourceSegmentsMismatchingResourceSegments 请确保嵌套资源的名称和类型中包含正确数量的段。Make sure nested resource has correct number of segments in name and type. 解决资源段Resolve resource segments
MissingRegistrationForLocationMissingRegistrationForLocation  检查资源提供程序注册状态,以及支持的位置。Check resource provider registration status and supported locations. 解决注册问题Resolve registration
MissingSubscriptionRegistrationMissingSubscriptionRegistration  向资源提供程序注册订阅。Register your subscription with the resource provider. 解决注册问题Resolve registration
NoRegisteredProviderFoundNoRegisteredProviderFound  检查资源提供程序注册状态。Check resource provider registration status. 解决注册问题Resolve registration
NotFoundNotFound  你可能在尝试部署与父资源并行的依赖资源。You might be attempting to deploy a dependent resource in parallel with a parent resource. 请检查是否需要添加依赖项。Check if you need to add a dependency. 解决依赖项问题Resolve dependencies
OperationNotAllowedOperationNotAllowed  部署所尝试的操作超出订阅、资源组或区域的配额。The deployment is attempting an operation that exceeds the quota for the subscription, resource group, or region. 请尽可能修改部署,使之保持在配额范围内。If possible, revise your deployment to stay within the quotas. 否则,请考虑请求更改配额。Otherwise, consider requesting a change to your quotas. 解决配额问题Resolve quotas
ParentResourceNotFoundParentResourceNotFound  确保在创建子资源之前存在父资源。Make sure a parent resource exists before creating the child resources. 解决父资源问题Resolve parent resource
PasswordTooLongPasswordTooLong 你可能选择了包含太多字符的密码,或在将密码值作为参数传递之前将其转换成了一个安全字符串。You might have selected a password with too many characters, or converted your password value to a secure string before passing it as a parameter. 如果模板包括一个安全字符串参数,则不需要将值转换为安全字符串。If the template includes a secure string parameter, you don't need to convert the value to a secure string. 请以文本形式提供密码值。Provide the password value as text.
PrivateIPAddressInReservedRangePrivateIPAddressInReservedRange  指定的 IP 地址包括 Azure 所需的地址范围。The specified IP address includes an address range required by Azure. 请更改 IP 地址,避免使用保留的范围。Change IP address to avoid reserved range. IP 地址IP addresses
PrivateIPAddressNotInSubnetPrivateIPAddressNotInSubnet  指定的 IP 地址位于子网范围之外。The specified IP address is outside of the subnet range. 请更改 IP 地址,使之位于子网范围之内。Change IP address to fall within subnet range. IP 地址IP addresses
PropertyChangeNotAllowedPropertyChangeNotAllowed  已部署资源上的某些属性不能更改。Some properties can't be changed on a deployed resource. 更新资源时,请仅更改允许的属性。When updating a resource, limit your changes to permitted properties.
RequestDisallowedByPolicyRequestDisallowedByPolicy 订阅中的某个资源策略阻止你在部署期间尝试执行的操作。Your subscription includes a resource policy that prevents an action you're trying to perform during deployment. 请找出阻止该操作的策略。Find the policy that blocks the action. 如果可能,请更改部署,使之符合策略的限制。If possible, change your deployment to meet the limitations from the policy. 解决策略问题Resolve policies
ReservedResourceNameReservedResourceName 提供不包含保留名称的资源名称。Provide a resource name that doesn't include a reserved name. 保留的资源名称Reserved resource names
ResourceGroupBeingDeletedResourceGroupBeingDeleted  等待删除操作完成。Wait for deletion to complete.
ResourceGroupNotFoundResourceGroupNotFound  检查部署的目标资源组的名称。Check the name of the target resource group for the deployment. 目标资源组必须已存在于订阅中。The target resource group must already exist in your subscription. 请检查订阅上下文。Check your subscription context. Azure CLI PowerShellAzure CLI PowerShell
ResourceNotFoundResourceNotFound  部署引用了一个无法解析的资源。Your deployment references a resource that can't be resolved. 请验证所使用的 reference 函数是否包括方案所需的参数。Verify that your use of the reference function includes the parameters required for your scenario. 解决引用问题Resolve references
ResourceQuotaExceededResourceQuotaExceeded  部署尝试创建的资源超过了订阅、资源组或区域的配额。The deployment is trying to create resources that exceed the quota for the subscription, resource group, or region. 请尽可能修改基础结构,使之保持在配额范围内。If possible, revise your infrastructure to stay within the quotas. 否则,请考虑请求更改配额。Otherwise, consider requesting a change to your quotas. 解决配额问题Resolve quotas
SkuNotAvailableSkuNotAvailable  选择可在所选位置中使用的 SKU(例如 VM 大小)。Select SKU (such as VM size) that is available for the location you've selected. 解决 SKU 问题Resolve SKU
StorageAccountAlreadyExistsStorageAccountAlreadyExists  为存储帐户提供唯一名称。Provide a unique name for the storage account. 解析存储帐户名称Resolve storage account name
StorageAccountAlreadyTakenStorageAccountAlreadyTaken  为存储帐户提供唯一名称。Provide a unique name for the storage account. 解析存储帐户名称Resolve storage account name
StorageAccountNotFoundStorageAccountNotFound  检查尝试使用的存储帐户的订阅、资源组和名称。Check the subscription, resource group, and name of the storage account that you're trying to use.
SubnetsNotInSameVnetSubnetsNotInSameVnet  一个虚拟机只能有一个虚拟网络。A virtual machine can only have one virtual network. 部署多个 NIC 时,请确保它们属于同一虚拟网络。When deploying several NICs, make sure they belong to the same virtual network. 多个 NICMultiple NICs
TemplateResourceCircularDependencyTemplateResourceCircularDependency 删除不必要的依赖项。Remove unnecessary dependencies. 解决循环依赖项Resolve circular dependencies
TooManyTargetResourceGroupsTooManyTargetResourceGroups 减少单个部署的资源组数。Reduce number of resource groups for a single deployment. 跨资源组部署Cross resource group deployment

查找错误代码Find error code

可能会出现两种类型的错误:There are two types of errors you can receive:

  • 验证错误validation errors
  • 部署错误deployment errors

验证错误源于部署之前可确定的方案。Validation errors arise from scenarios that can be determined before deployment. 原因包括模板中的语法错误,或尝试部署超出订阅配额的资源。They include syntax errors in your template, or trying to deploy resources that would exceed your subscription quotas. 部署错误起源于部署过程中出现的情况。Deployment errors arise from conditions that occur during the deployment process. 原因包括尝试访问并行部署的资源。They include trying to access a resource that is being deployed in parallel.

两种类型的错误都会返回用于对部署进行故障排除的错误代码。Both types of errors return an error code that you use to troubleshoot the deployment. 两种类型的错误都会显示在活动日志中。Both types of errors appear in the activity log. 但是,验证错误不会显示在部署历史记录中,因为部署从未启动。However, validation errors don't appear in your deployment history because the deployment never started.

验证错误Validation errors

通过门户部署时,提交值后会看到验证错误。When deploying through the portal, you see a validation error after submitting your values.


选择消息获取更多详细信息。Select the message for more details. 下图显示了一条 InvalidTemplateDeployment 错误,以及一条指出策略阻止了部署的消息。In the following image, you see an InvalidTemplateDeployment error and a message that indicates a policy blocked deployment.


部署错误Deployment errors

如果操作通过验证但在部署期间失败,将收到部署错误。When the operation passes validation, but fails during deployment, you get a deployment error.

若要通过 PowerShell 查看部署错误代码和消息,请使用:To see deployment error codes and messages with PowerShell, use:

(Get-AzResourceGroupDeploymentOperation -DeploymentName exampledeployment -ResourceGroupName examplegroup).Properties.statusMessage

若要通过 Azure CLI 查看部署错误代码和消息,请使用:To see deployment error codes and messages with Azure CLI, use:

az group deployment operation list --name exampledeployment -g examplegroup --query "[*].properties.statusMessage"

在门户中,选择通知。In the portal, select the notification.


查看有关部署的更多详细信息。You see more details about the deployment. 选择查找有关错误的详细信息的选项。Select the option to find more information about the error.


看到错误消息和错误代码。You see the error message and error codes. 请注意有两个错误代码。Notice there are two error codes. 第一个错误代码 (DeploymentFailed) 表示常规错误,不提供解决错误所需的详细信息 。The first error code (DeploymentFailed) is a general error that doesn't provide the details you need to solve the error. 第二个错误代码 (StorageAccountNotFound) 提供所需的详细信息。The second error code (StorageAccountNotFound) provides the details you need.


启用调试日志记录Enable debug logging

有时需要有关请求和响应的详细信息才能了解出现的问题。Sometimes you need more information about the request and response to learn what went wrong. 部署过程中,可以请求在部署期间记录更多信息。During deployment, you can request that additional information is logged during a deployment.


在 PowerShell 中,将 DeploymentDebugLogLevel 参数设置为 All、ResponseContent 或 RequestContent。In PowerShell, set the DeploymentDebugLogLevel parameter to All, ResponseContent, or RequestContent.

New-AzResourceGroupDeployment `
  -Name exampledeployment `
  -ResourceGroupName examplegroup `
  -TemplateFile c:\Azure\Templates\storage.json `
  -DeploymentDebugLogLevel All

使用以下 cmdlet 检查请求内容:Examine the request content with the following cmdlet:

(Get-AzResourceGroupDeploymentOperation `
-DeploymentName exampledeployment `
-ResourceGroupName examplegroup).Properties.request `
| ConvertTo-Json

或者,使用以下命令检查响应内容:Or, the response content with:

(Get-AzResourceGroupDeploymentOperation `
-DeploymentName exampledeployment `
-ResourceGroupName examplegroup).Properties.response `
| ConvertTo-Json

此信息可帮助确定模板中某个值的设置是否错误。This information can help you determine whether a value in the template is being incorrectly set.

Azure CLIAzure CLI

目前,Azure CLI 不支持启用调试日志记录,但可以检索调试日志记录。Currently, Azure CLI doesn't support turning on debug logging, but you can retrieve debug logging.

使用以下命令检查部署操作:Examine the deployment operations with the following command:

az group deployment operation list \
  --resource-group examplegroup \
  --name exampledeployment

使用以下命令检查请求内容:Examine the request content with the following command:

az group deployment operation list \
  --name exampledeployment \
  -g examplegroup \
  --query [].properties.request

使用以下命令检查响应内容:Examine the response content with the following command:

az group deployment operation list \
  --name exampledeployment \
  -g examplegroup \
  --query [].properties.response

嵌套模板Nested template

若要记录嵌套模板的调试信息,请使用 debugSetting 元素。To log debug information for a nested template, use the debugSetting element.

    "apiVersion": "2016-09-01",
    "name": "nestedTemplate",
    "type": "Microsoft.Resources/deployments",
    "properties": {
        "mode": "Incremental",
        "templateLink": {
            "uri": "{template-uri}",
            "contentVersion": ""
        "debugSetting": {
           "detailLevel": "requestContent, responseContent"

创建故障排除模板Create a troubleshooting template

在某些情况下,排查模板问题的最简单方法是测试模板的部件。In some cases, the easiest way to troubleshoot your template is to test parts of it. 可以创建一个简化的模板,专注于调查你认为是错误起源的部件。You can create a simplified template that enables you to focus on the part that you believe is causing the error. 例如,假设在引用资源时收到错误消息。For example, suppose you're receiving an error when referencing a resource. 请勿处理整个模板,而是创建可返回可能导致问题的部件的模板。Rather than dealing with an entire template, create a template that returns the part that may be causing your problem. 这可以帮助确定传入的是否是正确的参数,是否正确使用模板函数,以及是否获得所需的资源。It can help you determine whether you're passing in the right parameters, using template functions correctly, and getting the resource you expect.

  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "",
  "parameters": {
    "storageName": {
        "type": "string"
    "storageResourceGroup": {
        "type": "string"
  "variables": {},
  "resources": [],
  "outputs": {
    "exampleOutput": {
        "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageName')), '2016-05-01')]",
        "type" : "object"

或者,假设收到部署错误,而你认为它与依赖关系设置错误有关。Or, suppose you're getting deployment errors that you believe are related to incorrectly set dependencies. 将模板分解为多个简化模板,对其进行测试。Test your template by breaking it into simplified templates. 首先,创建仅部署单项资源(如 SQL Server)的模板。First, create a template that deploys only a single resource (like a SQL Server). 确保已正确定义该资源时,再添加依赖于它的资源(如 SQL 数据库)。When you're sure you have that resource correctly defined, add a resource that depends on it (like a SQL Database). 正确定义这两项资源后,添加其他从属资源(如审核策略)。When you have those two resources correctly defined, add other dependent resources (like auditing policies). 在每个测试部署之间,删除资源组,以确保充分测试依赖关系。In between each test deployment, delete the resource group to make sure you adequately testing the dependencies.

后续步骤Next steps