Troubleshoot private endpoint DNS resolution failure in Azure Private Link

Summary

This article provides step-by-step diagnostics to identify and resolve problems where a private endpoint fully-qualified domain name (FQDN) resolves to a public IP or returns NXDOMAIN from a virtual network (VNet) or on-premises network.

A private endpoint FQDN resolving to a public IP (or returning NXDOMAIN) is usually caused by these reasons:

• The private DNS zone isn't linked to the querying VNet (the most common reason).
• The A record is missing or stale.
• Custom Domain Name System (DNS) or conditional forwarders aren't forwarding privatelink.* queries to Azure DNS (for example, 168.63.129.16).
• The private DNS zone overrides the entire namespace causing NXDOMAIN for resources without A records.

Symptoms

You might encounter one or more of the following symptoms:

• nslookup or dig values for a private endpoint FQDN return a public IP instead of a private IP (for example, 10.x, 172.16–31.x, or 192.168.x).
• nslookup returns ** server can't find [FQDN]: NXDOMAIN from inside the VNet.
• The application receives 403 Forbidden or TCP connection does not allow access errors when connecting to a platform-as-a-service (PaaS) that has firewall rules denying public access. The FQDN then resolves to the public endpoint.
• The Azure portal shows the private endpoint status as Approved but connectivity from the VNet still fails.
• On-premises clients can't reach the private endpoint even though the VPN or Azure ExpressRoute link is healthy.

Prerequisites

To troubleshoot this issue, you need the following items:

• Permissions required: Reader role on the private endpoint resource group and private DNS zone, and Private DNS Zone Contributor permissions for write operations.
• Tools: Azure CLI 2.x or an AI agent with Azure MCP or Azure CLI access.
• Required variables and examples of those variables, as shown in the following table

TIP: Each script that's provided in the following sections prompts you for the required values interactively. To open Cloud Shell and answer the prompts, select Try It. The values are cached for that session. Therefore, you enter them only one time.

Diagnostic steps

Step 1

Check what IP address the FQDN currently resolves to. Determine whether the problem is confirmed, and whether it resolves to public, private, or not at all.

Run the following commands in Azure CLI or a command line interface (CLI) tool:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$FQDN" ] && read -rp "FQDN to resolve (e.g. mystorageaccount.blob.core.windows.net): " FQDN

echo "--- Resolving $FQDN ---"
nslookup "$FQDN"

Interpret the results

Step 2

Check whether the private endpoint exists, is in Approved state, and what private IP is assigned to it.

Run the following commands in 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 "$PE_NAME" ] && read -rp "Private Endpoint Name: " PE_NAME

az network private-endpoint show \
  --name "$PE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "{name:name, provisioningState:provisioningState, connectionStatus:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status, nicId:networkInterfaces[0].id, customDnsConfigs:customDnsConfigs}" \
  --output json

Then, retrieve the private IP from the network adapter (also known as a network interface card (NIC)):

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

NIC_ID=$(az network private-endpoint show \
  --name "$PE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "networkInterfaces[0].id" \
  --output tsv)

az network nic show \
  --ids "$non_ID" \
  --query "ipConfigurations[].{name:name, privateIpAddress:privateIPAddress, fqdns:privateLinkConnectionProperties.fqdns}" \
  --output json

Record the private IP (for example, 10.0.1.5). This is the IP that the FQDN should resolve to.

Interpret the results

Step 3

Check whether a private DNS zone exists for the correct privatelink.* namespace and whether it contains an A record pointing to the private endpoint IP.

Run the following commands in Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:      " SUBSCRIPTION
[ -z "$DNS_ZONE_RG" ] && read -rp "DNS Zone Resource Group (may differ from PE RG): " DNS_ZONE_RG
[ -z "$DNS_ZONE_NAME" ] && read -rp "Private DNS Zone Name (e.g. privatelink.blob.core.windows.net): " DNS_ZONE_NAME

az network private-dns record-set a list \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "[].{Name:name, TTL:ttl, IPv4Address:aRecords[0].ipv4Address}" \
  --output table

Look for an A record whose name matches the short name of the failing FQDN (the part before .privatelink.*). For example, if the failing FQDN is mystorageaccount.blob.core.windows.net, look for an A record that's named mystorageaccount.

Interpret the results

Step 4

Check whether the private DNS zone is linked to the VNet from which DNS queries originate.

Run the following commands in Azure CLI:

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

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

Interpret the results

Step 5

Check whether the VNet uses custom DNS servers (instead of Azure-provided DNS) and whether those custom servers forward privatelink.* queries to Azure DNS (168.63.129.16).

Run the following commands in Azure CLI:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID: " SUBSCRIPTION
[ -z "$VNET_RG" ] && read -rp "VNet Resource Group: " VNET_RG
[ -z "$VNET_NAME" ] && read -rp "VNet Name:       " VNET_NAME

az network vnet show \
  --name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "{name:name, dnsServers:dhcpOptions.dnsServers}" \
  --output json

Interpret the results

Decision map

Use the following decision map table to determine the appropriate next steps based on your diagnostic results.

Resolution A

The private DNS zone exists and contains the correct A record, but it isn't linked to the VNet from which DNS queries originate. Without a VNet link, Azure DNS can't consult the private zone, and returns the public IP from the service's public DNS.

Run the following commands in Azure CLI (when applicable).

1. Verify the VNet resource ID:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID: " SUBSCRIPTION
[ -z "$VNET_RG" ] && read -rp "VNet Resource Group: " VNET_RG
[ -z "$VNET_NAME" ] && read -rp "VNet Name:       " VNET_NAME

az network vnet show \
  --name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "id" \
  --output tsv

Record the VNet resource ID.

2. Create the VNet link on the private DNS zone.

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:      " SUBSCRIPTION
[ -z "$DNS_ZONE_RG" ] && read -rp "DNS Zone Resource Group: " DNS_ZONE_RG
[ -z "$DNS_ZONE_NAME" ] && read -rp "Private DNS Zone Name: " DNS_ZONE_NAME
[ -z "$VNET_RG" ] && read -rp "VNet Resource Group:   " VNET_RG
[ -z "$VNET_NAME" ] && read -rp "VNet Name:             " VNET_NAME
[ -z "$LINK_NAME" ] && read -rp "Link Name (e.g. link-to-myVNet): " LINK_NAME

VNET_ID=$(az network vnet show \
  --name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "id" --output tsv)

az network private-dns link vnet create \
  --name "$LINK_NAME" \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --virtual-network "$VNET_ID" \
  --registration-enabled false

3. Verify the fix, and then rerun Step 1:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$FQDN" ] && read -rp "FQDN to resolve: " FQDN

nslookup "$FQDN"

The FQDN should now resolve to the private IP from Step 2. If it still resolves to a public IP, allow 1–2 minutes for propagation and retry.

If the VNet uses custom DNS servers, this fix alone is insufficient. Go to Resolution C.

Resolution B

The A record in the private DNS zone is missing, stale (pointing to a deleted endpoint's IP), or was never created. This problem occurs when you create the private endpoint without a DNS zone group, delete a sibling endpoint that shared the zone and triggered autocleanup, or manually create the zone without adding the record.

Run the following commands in Azure CLI (as applicable).

1. Get the private endpoint's expected private IP and FQDN:

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 "$PE_NAME" ] && read -rp "Private Endpoint Name: " PE_NAME

az network private-endpoint show \
  --name "$PE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --query "customDnsConfigs[].{fqdn:fqdn, ipAddresses:ipAddresses}" \
  --output json

Record the FQDN (the short name before privatelink.*) and the IP address.

For example, if the target is mystorageaccount.blob.core.windows.net:

• The A record name in zone privatelink.blob.core.windows.net is mystorageaccount.
• The IP is the private IP from the NIC (for example, 10.0.1.5).

2. Add the A record to the private DNS zone.

Option 1: Create the A record manually (immediate fix)

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:      " SUBSCRIPTION
[ -z "$DNS_ZONE_RG" ] && read -rp "DNS Zone Resource Group: " DNS_ZONE_RG
[ -z "$DNS_ZONE_NAME" ] && read -rp "Private DNS Zone Name: " DNS_ZONE_NAME
[ -z "$RECORD_NAME" ] && read -rp "A Record Name (e.g. mystorageaccount): " RECORD_NAME
[ -z "$PE_PRIVATE_IP" ] && read -rp "Private Endpoint IP (from B.1): " PE_PRIVATE_IP

az network private-dns record-set a add-record \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --record-set-name "$RECORD_NAME" \
  --ipv4-address "$PE_PRIVATE_IP"

Option 2: Create a DNS zone group (recommended for ongoing automanagement)

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

DNS_ZONE_ID=$(az network private-dns zone show \
  --name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "id" --output tsv)

az network private-endpoint dns-zone-group create \
  --endpoint-name "$PE_NAME" \
  --resource-group "$RG" \
  --subscription "$SUBSCRIPTION" \
  --name "default" \
  --zone-name "$DNS_ZONE_NAME" \
  --private-dns-zone "$DNS_ZONE_ID"

A DNS zone group automatically creates and manages A records when you create the private endpoint or change its IP. This approach is recommended for new deployments.

3. Verify the fix, and then rerun Step 1.

# ── Collect inputs (cached if already set in this session) ──
[ -z "$FQDN" ] && read -rp "FQDN to resolve: " FQDN

nslookup "$FQDN"

The FQDN should now resolve to the private endpoint IP. If it still returns NXDOMAIN or a public IP, check the VNet link (Step 4). The zone might not be linked.

Resolution C

The VNet uses custom DNS servers, such as Active Directory domain controllers, on-premises DNS servers, or a custom DNS VM. These custom servers don't forward privatelink.* queries to Azure DNS (168.63.129.16), so the private DNS zone is never consulted.

This issue is the most common cause of problems for on-premises clients that connect through VPN or ExpressRoute.

Run the following commands in Azure CLI (when applicable).

1. Identify the custom DNS servers:

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID: " SUBSCRIPTION
[ -z "$VNET_RG" ] && read -rp "VNet Resource Group: " VNET_RG
[ -z "$VNET_NAME" ] && read -rp "VNet Name:       " VNET_NAME

az network vnet show \
  --name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "dhcpOptions.dnsServers" \
  --output json

Record the custom DNS server IPs.

2. Configure conditional forwarders on the custom DNS server.

This step is performed on the custom DNS server (not by using Azure CLI). Configure a conditional forwarder for the privatelink.* zone that forwards to 168.63.129.16:

Windows DNS Server

1. Open DNS Manager.
2. Right-click Conditional Forwarders > New Conditional Forwarder.
3. For DNS Domain, enter the private link zone name, such as privatelink.blob.core.windows.net.
4. For IP address, enter 168.63.129.16.
5. Select OK.

BIND (Linux)

Add the following to /etc/bind/named.conf.local (or your site-specific configuration file):

zone "privatelink.blob.core.windows.net" {
    type forward;
    forwarders { 168.63.129.16; };
};

Alternative - Deploy Azure DNS Private Resolver (recommended for hybrid scenarios)

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID: " SUBSCRIPTION
[ -z "$RESOLVER_RG" ] && read -rp "Resolver Resource Group: " RESOLVER_RG
[ -z "$RESOLVER_NAME" ] && read -rp "DNS Resolver Name: " RESOLVER_NAME
[ -z "$VNET_NAME" ] && read -rp "VNet Name:       " VNET_NAME
[ -z "$VNET_RG" ] && read -rp "VNet Resource Group: " VNET_RG
[ -z "$INBOUND_SUBNET" ] && read -rp "Inbound Endpoint Subnet Name: " INBOUND_SUBNET

VNET_ID=$(az network vnet show \
  --name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "id" --output tsv)

SUBNET_ID=$(az network vnet subnet show \
  --name "$INBOUND_SUBNET" \
  --vnet-name "$VNET_NAME" \
  --resource-group "$VNET_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "id" --output tsv)

az dns-resolver create \
  --name "$RESOLVER_NAME" \
  --resource-group "$RESOLVER_RG" \
  --subscription "$SUBSCRIPTION" \
  --location $(az network vnet show --name "$VNET_NAME" --resource-group "$VNET_RG" --subscription "$SUBSCRIPTION" --query "location" --output tsv) \
  --id "$VNET_ID"

az dns-resolver inbound-endpoint create \
  --name "inbound-endpoint" \
  --dns-resolver-name "$RESOLVER_NAME" \
  --resource-group "$RESOLVER_RG" \
  --subscription "$SUBSCRIPTION" \
  --ip-configurations "[{private-ip-allocation-method:Dynamic,id:$SUBNET_ID}]"

After you deploy the inbound endpoint, configure on-premises DNS to forward privatelink.* queries to the inbound endpoint's private IP (retrieve with az dns-resolver inbound-endpoint show).

3. Verify the fix, and then rerun Step 1 from the affected client.

# ── Collect inputs (cached if already set in this session) ──
[ -z "$FQDN" ] && read -rp "FQDN to resolve: " FQDN

nslookup "$FQDN"

The FQDN should now resolve to the private endpoint IP. On Windows clients, flush the DNS cache by running ipconfig /flushdns.

Resolution D

A private DNS zone for the privatelink.* namespace is linked to the VNet and overrides all names in that namespace. Resources that don't have an A record in the zone return NXDOMAIN instead of passing through to a public DNS. This condition commonly occurs when you create the zone for one private endpoint, but other resources in the same service namespace (that aren't private endpoints) also have to resolve.

Run the following commands in Azure CLI (when applicable).

1. List all A records in the zone and identify which resource is missing:

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

az network private-dns record-set a list \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --query "[].{Name:name, TTL:ttl, IPv4Address:aRecords[0].ipv4Address}" \
  --output table

Identify the resource FQDN that's returning NXDOMAIN. If it's a resource that should resolve publicly (not a private endpoint), it won't have an A record here.

2. Use one of the following fixes, as appropriate:

Option 1: Enable NxDomainRedirect on the VNet link (recommended)

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:      " SUBSCRIPTION
[ -z "$DNS_ZONE_RG" ] && read -rp "DNS Zone Resource Group: " DNS_ZONE_RG
[ -z "$DNS_ZONE_NAME" ] && read -rp "Private DNS Zone Name: " DNS_ZONE_NAME
[ -z "$LINK_NAME" ] && read -rp "VNet Link Name (from Step 4 output): " LINK_NAME

az network private-dns link vnet update \
  --name "$LINK_NAME" \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --resolution-policy NxDomainRedirect

With NxDomainRedirect, if a query to the private DNS zone returns NXDOMAIN, Azure DNS falls back to public resolution. This approach allows nonprivate endpoint resources in the same namespace to resolve normally.

Option 2: Add explicit A records for nonprivate endpoint resources that need to resolve

# ── Collect inputs (cached if already set in this session) ──
[ -z "$SUBSCRIPTION" ] && read -rp "Subscription ID:      " SUBSCRIPTION
[ -z "$DNS_ZONE_RG" ] && read -rp "DNS Zone Resource Group: " DNS_ZONE_RG
[ -z "$DNS_ZONE_NAME" ] && read -rp "Private DNS Zone Name: " DNS_ZONE_NAME
[ -z "$RECORD_NAME" ] && read -rp "Record Name (e.g. otherresource): " RECORD_NAME
[ -z "$PUBLIC_IP" ] && read -rp "Public IP of the resource: " PUBLIC_IP

az network private-dns record-set a add-record \
  --zone-name "$DNS_ZONE_NAME" \
  --resource-group "$DNS_ZONE_RG" \
  --subscription "$SUBSCRIPTION" \
  --record-set-name "$RECORD_NAME" \
  --ipv4-address "$PUBLIC_IP"

3. Verify the fix, and then rerun Step 1 for the affected FQDN.

# ── Collect inputs (cached if already set in this session) ──
[ -z "$FQDN" ] && read -rp "FQDN to resolve: " FQDN

nslookup "$FQDN"

The resource should now resolve correctly. Private endpoints resolve to their private IP, and nonprivate endpoint resources resolve through public DNS fallback.

References

• Azure Private Endpoint DNS configuration
• Azure Private DNS zone overview
• Azure DNS Private Resolver
• Integrate Private Link with Azure DNS Private Resolver
• Virtual network links on private DNS zones
• Troubleshoot Azure Private Endpoint connectivity problems