highIntermediateSymptom-first#dns#private-dns#vnet#resolution#networking

Private DNS zone not resolving — VNet link missing or broken

nslookup for a private endpoint FQDN returns NXDOMAIN from a VM in the VNet

Likely source:connectivityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • nslookup for a private endpoint FQDN returns NXDOMAIN from a VM in the VNet
  • az network private-dns zone list shows the zone but VNet link is absent
  • Application cannot reach Azure services via private endpoint FQDN

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Private DNS zone VNet links

    az network private-dns link vnet list --resource-group <RG> --zone-name <ZONE> --query "[].{name:name,vnet:virtualNetworkId}" -o table

  • VNet link status

    az network private-dns link vnet list --resource-group <RG> --zone-name <ZONE> --query "[].registrationEnabled" -o tsv

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • az network private-dns link vnet list returns empty or wrong VNet
  • VMs in the VNet cannot resolve the zone FQDN

Confirm before fixing

az network private-dns link vnet list --resource-group <RG> --zone-name <ZONE> --query "[].virtualNetworkId" -o tsv
READ

Check which VNets are linked

Fix

az network private-dns link vnet create --resource-group <RG> --zone-name <ZONE> --name <LINK-NAME> --virtual-network <VNET> --registration-enabled false
CHANGE

Create the VNet link to the private DNS zone

Expected: Private DNS zone VNet link created.

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
az network private-dns link vnet list --resource-group <RG> --zone-name <ZONE> --query "[].{name:name,vnet:virtualNetworkId}" -o table
READ

Check existing VNet links

2
az network private-dns link vnet create --resource-group <RG> --zone-name <ZONE> --name <LINK-NAME> --virtual-network <VNET> --registration-enabled false
CHANGE

Create the missing VNet link

3
az vm run-command invoke --resource-group <RG> --name <VM-NAME> --command-id RunShellScript --scripts "nslookup <PRIVATE-FQDN>" --query "output[0]" -o tsv
READ

Verify resolution from the VM

Prevention

  • Link all VNets that need to resolve private endpoints to the private DNS zone.
  • Use Azure Policy to enforce private DNS zone links on every new VNet.
  • Test DNS resolution as part of any new private endpoint deployment.
  • Document private DNS zone topology in your network runbook.

Related runbooks

Same stack, same failure family — worth a skim.

VNet peering traffic blocked — non-overlapping CIDR or gateway requiredhigh

VMs in peered VNets cannot reach each other

AzureIntermediate3 causes
Open runbook
DNS resolution failing inside pods — CoreDNS issuescritical

curl: Could not resolve host inside pods

KubernetesIntermediate2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.