Troubleshoot an Azure private DNS zone that you can't delete or migrate

Summary

Azure private DNS zone delete, migrate, and resource-group-move operations almost always fail because of an unresolved dependency, not a platform refusal. Four causes drive most failures: a virtual network link still exists on the zone (often from a deleted or cross-subscription VNet that no longer renders in the portal), a CanNotDelete resource lock is in place, the zone exceeds the default record-set quota during a bulk migration, or the operation succeeded and the portal is lagging during ARM convergence. This article helps you identify the cause and how to clear it.

Symptoms

You might experience one or more of the following symptoms:

• The portal or CLI returns The DNS zone <zone> can not be deleted because it has virtual network links (PreconditionFailed / DnsZoneInUse).
• az network private-dns zone delete fails with Cannot delete resource while nested resources exist even though az network private-dns link vnet list returns an empty array.
• A delete or move operation fails with ScopeLocked or Cannot proceed with operation because resource <id> used by resource <id> is not in Succeeded state.
• A bulk record-set import or migration aborts with RecordSetCountLimitExceeded or Quota exceeded for resource type.
• After a Move-AzResource or resource-group move, records appear missing in the portal but az network private-dns record-set list still returns them.
• Repeated retries from the portal succeed only after some delay, with no configuration change between attempts.

Prerequisites

• Permissions required: Private DNS Zone Contributor (or equivalent) on the zone, plus Microsoft.Authorization/locks/* to inspect and remove resource locks.
• Tools: Azure CLI 2.50 or later (or an AI agent with Azure CLI access). jq is available in Cloud Shell.
• What you need before starting:

Diagnostic steps

These steps are read-only. They don't make any changes to your environment.

Step 1

What this step checks: It captures the exact error returned by the failing delete or migrate operation, plus the zone's current dependency counts. The error code routes you to the correct branch. If you skip this check, the rest of this guide is wasted effort. This step only reads state; it doesn't retry the delete.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

# Read-only: current zone state and dependency counts.
az network private-dns zone show \
  --name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "{state:provisioningState, vnetLinks:numberOfVirtualNetworkLinks, recordSets:numberOfRecordSets}" \
  --output json 2>&1 || true

# Read-only: the error code from your most recent failed delete or move.
ZONE_ID="/subscriptions/$SUBSCRIPTION/resourceGroups/$RG/providers/Microsoft.Network/privateDnsZones/$ZONE_NAME"
az monitor activity-log list \
  --resource-id "$ZONE_ID" \
  --offset 6h \
  --query "reverse(sort_by([?status.value=='Failed'], &eventTimestamp))[0:5].{time:eventTimestamp, op:operationName.localizedValue, status:status.value, code:properties.statusCode, sub:subStatus.value}" \
  --output table

Interpret the result

Route by the failed-operation error code first - it's the primary discriminator. Read the code (and sub) of the most recent failed operation from the activity-log table in the preceding section. If the activity log doesn't yet record the failure, use the error code or error text your delete or move command returned. Match the first row in the following table whose error code matches, and follow it.

The vnetLinks and recordSets counts from the zone show call are context only - they never override the error code. A healthy, normally-linked zone routinely reports vnetLinks greater than 0, so a zone failing for a lock, quota, or visibility-lag reason also shows vnetLinks > 0. The link count routes you to Step 2 only when the error itself is a virtual-network-link precondition (PreconditionFailed / DnsZoneInUse). A non-link error code always wins over the link count.

Step 2

What this check does: It checks for visible virtual network links on the zone. The standard delete path enforces these dependencies.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az network private-dns link vnet list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --output table

Interpret the result

Step 3

What this check does: Finds orphaned or invisible VNet links by using the raw ARM API. The standard link vnet list command can omit links whose backing VNet was deleted, lives in a different subscription, or is stuck mid-provisioning. Calling the management plane directly returns the authoritative list.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

# Authoritative enumeration of every virtualNetworkLink child resource on
# the zone, including links whose VNet has been deleted.
az rest --method get \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RG/providers/Microsoft.Network/privateDnsZones/$ZONE_NAME/virtualNetworkLinks?api-version=2024-06-01" \
  --query "value[].{name:name, state:properties.provisioningState, vnet:properties.virtualNetwork.id, registration:properties.registrationEnabled}" \
  --output table

Interpret the result

Step 4

What this check does: Resource locks at zone, resource-group, and subscription scope. A CanNotDelete lock at any ancestor scope blocks the delete and is invisible if you only inspect the zone itself.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az account set --subscription "$SUBSCRIPTION"

echo "─── Locks on zone ───"
az lock list \
  --resource-group "$RG" \
  --resource-name "$ZONE_NAME" \
  --resource-type Microsoft.Network/privateDnsZones \
  --output table

echo "─── Locks on resource group ───"
az lock list --resource-group "$RG" --output table

echo "─── Locks on subscription ───"
az lock list --output table

Interpret the result

Step 5

What this check does: It checks whether the zone is at or near the per-zone record-set limit. Bulk migrations (Azure DNS Migration Tool, Terraform plans, ARM exports) commonly hit this limit without a clear error.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

# Count record-sets in the zone. The default per-zone limit is 25,000
# record sets; the default records-per-record-set limit is 20.
RECORDSET_COUNT=$(az network private-dns record-set list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "length(@)" \
  --output tsv)

echo "Record sets in $ZONE_NAME: $RECORDSET_COUNT"

# Find any record set with > 15 records — close to the 20-record default.
az network private-dns record-set list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "[?length(aRecords || \`[]\`) > \`15\` || length(aaaaRecords || \`[]\`) > \`15\` || length(txtRecords || \`[]\`) > \`15\`].{name:name, type:type}" \
  --output table

Interpret the result

Step 6

What this check does: It verifies whether the operation actually succeeded and if you're seeing portal cache lag. After a resource-group move or a long-running delete, the portal can show the zone for several minutes after ARM already removed it. CLI is the source of truth.

Run this command

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

echo "─── Direct read against the zone ───"
az network private-dns zone show \
  --name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "{name:name, state:provisioningState, recordCount:numberOfRecordSets}" \
  --output json 2>&1 || true

echo "─── Recent activity log for the zone ───"
ZONE_ID="/subscriptions/$SUBSCRIPTION/resourceGroups/$RG/providers/Microsoft.Network/privateDnsZones/$ZONE_NAME"
az monitor activity-log list \
  --resource-id "$ZONE_ID" \
  --offset 24h \
  --query "[?status.value=='Failed' || operationName.value=='Microsoft.Network/privateDnsZones/delete' || operationName.value=='Microsoft.Resources/subscriptions/resourceGroups/moveResources/action'].{time:eventTimestamp, op:operationName.localizedValue, status:status.value, code:properties.statusCode, corr:correlationId}" \
  --output table

Interpret the result

Decision map

Resolution A

Root cause: One or more virtual network links still reference the zone. Azure private DNS rejects zone deletion while any link exists, even links you no longer use.

A.1

Confirm the exact link names from Step 2. For each link, also note registrationEnabled - if it was the auto-registration link for a VNet, removing it stops auto-registration on that VNet.

Azure CLI (read-only):

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az network private-dns link vnet list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "[].{name:name, vnet:virtualNetwork.id, registration:registrationEnabled, state:provisioningState}" \
  --output table

Record each name value; you use it in A.2.

A.2

⚠️ WRITE OPERATION - requires customer approval before executing

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME
[ -z "$LINK_NAME" ] && read -rp "Link name to delete:    " LINK_NAME

az network private-dns link vnet delete \
  --name "$LINK_NAME" \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --yes

Repeat for every link returned by A.1.

A.3

Re-run Step 2. When the list is empty, retry the original delete:

⚠️ WRITE OPERATION - requires customer approval before executing

Azure CLI:

[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az network private-dns zone delete \
  --name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --yes

If deletion still fails with nested resources exist, proceed to Resolution B.

Resolution B

Root cause: The zone has one or more orphaned virtual network links - child resources whose backing VNet was deleted, lives in a foreign subscription you no longer have access to, or is stuck in a non-terminal provisioning state. The standard link vnet commands omit these links because they can't resolve the VNet target, but the link object itself still exists and still blocks the parent zone.

B.1

From Step 3, capture the full resource ID of every orphaned link. Build it from the zone scope:

Azure CLI (read-only):

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az rest --method get \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RG/providers/Microsoft.Network/privateDnsZones/$ZONE_NAME/virtualNetworkLinks?api-version=2024-06-01" \
  --query "value[].id" \
  --output tsv

B.2

⚠️ WRITE OPERATION - requires customer approval before executing

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$LINK_ID" ] && read -rp "Orphaned link resource ID: " LINK_ID

az rest --method delete \
  --url "https://management.azure.com${LINK_ID}?api-version=2024-06-01"

If az rest delete returns 202 Accepted with no body, the delete is asynchronous - wait 30-60 seconds for ARM to converge. If it returns 409 Conflict with LinkedScopeIsNotInSucceededState, the link is stuck mid-update. Let it converge and retry, or open a support case with the correlation ID.

Repeat for every orphaned link from B.1.

B.3

Re-run Step 3. When the list is empty, retry the zone delete from A.3. If links keep reappearing, ARM didn't finish propagating the upstream change (for example a recently-deleted VNet). Wait 10 minutes and re-check before opening a support case.

Resolution C

Root cause: A CanNotDelete or ReadOnly resource lock at the zone, resource-group, or subscription scope is blocking the delete. Both lock levels prevent deletion. ARM evaluates locks across scopes, so a lock at any ancestor scope is sufficient to block a child operation.

C.1

From Step 4, identify the lock that applies. Note the scope (zone, RG, or subscription), the lock's name, and (if known) the team or process that created it. Locks are usually placed deliberately - confirm with the owning team before removing.

C.2

⚠️ WRITE OPERATION - requires customer approval before executing

Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$LOCK_ID" ] && read -rp "Lock resource ID to delete: " LOCK_ID

az lock delete --ids "$LOCK_ID"

If the lock must remain in place for governance reasons, don't rely on downgrading it - a ReadOnly lock also blocks deletion. Either remove the lock for a coordinated maintenance window, scope it more tightly so it no longer covers the zone, or have the lock owner perform the delete.

C.3

Re-run Step 1. If the original error code was ScopeLocked and the lock list is now empty, retry the delete from A.3. If a different error returns, route via the Decision map.

Resolution D

Root cause: The zone is at or approaching the default record-set quota (25,000 record sets per private DNS zone) or the per-record-set limit (20 records of a single type). Bulk migrations and ARM template imports trip this gate without explicit pre-checks.

D.1

Decide between two paths based on Step 5:

• Splittable migration: You can partition the source zone across multiple destination zones (for example, by subdomain). Stage the migration in batches, each well below 25,000 record sets.
• Single-zone migration: The namespace must remain a single authoritative zone. File a quota-increase request before retrying.

D.2

To file a quota increase, open a support request scoped to the subscription and the Microsoft.Network provider. For the request type, select Service and subscription limits (quotas). For the quota type, select Networking → Private DNS. Specify the target record-set count and the zone name.

D.3

For staged migrations, plan batches that each leave headroom of at least 10% below the per-zone limit:

Azure CLI (read-only - sample to size a batch):

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

# Group record-sets by type to see where the volume is concentrated.
az network private-dns record-set list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "[].type" \
  --output tsv | sort | uniq -c | sort -rn

Use the type distribution to design batches that respect both the per-zone (25,000) and per-record-set (20 records) limits.

D.4

After the staged migration completes (or the quota increase is granted), re-run Step 5 and confirm RECORDSET_COUNT matches the expected total and no record set exceeds the per-set limit.

Resolution E

Root cause: The delete or move operation already succeeds at the ARM control-plane layer. The portal cache, downstream Resource Graph indexers, or peered services are still converging. This condition isn't an outage and retrying doesn't fix it.

E.1

Treat CLI as the source of truth. The portal is a view, not the system of record:

Azure CLI (read-only):

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Resource Group:         " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

# A clean ResourceNotFound here means the zone is gone in ARM.
az network private-dns zone show \
  --name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --output json 2>&1 || true

If this command returns ResourceNotFound, the zone is deleted. The portal reconciles within 15 minutes. Force a refresh by closing the resource blade and re-navigating from the resource group.

E.2

For records missing after RG move:

Azure CLI (read-only):

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:        " SUBSCRIPTION
[ -z "$RG" ] && read -rp "Destination Resource Group: " RG
[ -z "$ZONE_NAME" ] && read -rp "Private DNS Zone Name:  " ZONE_NAME

az network private-dns record-set list \
  --zone-name "$ZONE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "length(@)" \
  --output tsv

Compare this count to the count taken before the RG move. If the counts match, records are intact - don't restore from a backup. The portal blade for the destination zone might show 0 records for up to 30 minutes after a move. Don't retry the move.

E.3

If after 30 minutes the portal still shows the deleted zone or the record count still disagrees with E.2, open a support case by using the correlation IDs from Step 1 and Step 6.

Related articles

• Manage private DNS zones with Azure CLI
• Manage virtual network links with Azure CLI
• Move resources to a new resource group or subscription
• Lock resources to prevent unexpected changes
• Azure subscription and service limits — DNS