Troubleshoot Private Endpoint Connection Issues

On this page

Dedicated Clusters

This page outlines common private endpoint connection issues and possible resolutions.

Dedicated Clusters

Check the status of your AWS PrivateLink connections.

To view the status of each private endpoint:

In Atlas, go to the Network Access page for your project.
1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
2. If it's not already displayed, select your project from the Projects menu in the navigation bar.
3. In the sidebar, click Network Access under the Security heading.
  The Network Access page displays.
Click the Private Endpoint tab.
Review the statuses.
The Atlas Endpoint Service Status and Endpoint Status fields show the status of each private endpoint.

Refer to the following statuses to help you determine the state of your private endpoint connections:

Atlas Endpoint Service Status

Status	Description
Creating private link	Atlas is creating the network load balancer and VPC resources.
Failed	A system failure has occurred.
Available	The Atlas network load balancer and VPC endpoint service are created and ready to receive connection requests.
Deleting	Atlas is deleting the private endpoint service.

Endpoint Status

Status

Description

Not configured

Atlas created the network load balancer and VPC endpoint service, but AWS hasn't yet created the interface endpoint. Click Edit and complete the wizard to create the interface endpoint.

Pending acceptance

AWS has received the connection request from your interface endpoint to the Atlas VPC endpoint service.

Pending

AWS is establishing the connection between your interface endpoint and the Atlas VPC endpoint service.

Failed

AWS failed to establish a connection between Atlas VPC resources and the interface endpoint in your VPC. Click Edit, verify that the information you provided is correct, and then create the private endpoint again.

IMPORTANT: If your Interface Endpoint fails, you might see the following message:

No dns entries found for endpoint vpce-<guid>,
your endpoint must be provisioned in at least one subnet.
Click "Edit" to fix the problem.

This message indicates that you didn't specify a subnet when you created the AWS PrivateLink connection. To resolve this error:

Click Edit.
Click Back.
Specify at least one subnet.
Follow the remaining instructions to create the AWS PrivateLink connection.

Available

Atlas VPC resources are connected to the interface endpoint in your VPC. You can connect to Atlas clusters in this region using AWS PrivateLink.

Deleting

Atlas is removing the interface endpoint from the private endpoint service.

Make sure that your security groups are configured properly.

For each resource that needs to connect to your Atlas clusters using AWS PrivateLink, the resource's security group must allow outbound traffic to the interface endpoint's private IP addresses on all ports (1024-65535).
See Adding Rules to a Security Group for more information.
Your interface endpoint security group must allow inbound traffic on all ports from each resource that needs to connect to your Atlas clusters using AWS PrivateLink.
Access List instance IP addresses or security groups to allow traffic from them to reach the interface endpoint security group.

Obtain Private IPs with DNS Lookup

When a client in your VPC connects to an Atlas cluster using one of these private endpoint-aware connection strings, the client attempts to establish a connection to the load balancer in the Atlas VPC through one of the interface endpoints. Your client's DNS resolution mechanism handles which of the interface endpoints the hostname resolves to. If one interface endpoint is unavailable the next is used. This is opaque to the driver or other connection mechanism. The driver is only aware of the hostname in the SRV record or in the connection string.

SRV Record for DNS Seedlist Private Endpoint-Aware Connection Strings

The following example shows the SRV record for an AWS PrivateLink -enabled single-region cluster, showing three unique ports defined for pl-0-us-east-1-k45tj.mongodb.net:

$ nslookup -type=SRV _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net
Server: 127.0.0.53
Address: 127.0.0.53#53
Non-authoritative answer:
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1026 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1024 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1025 pl-0-us-east-1-k45tj.mongodb.net.

In the preceding example:

_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net is the SRV record that the mongodb+srv://cluster0-pl-0-k45tj.mongodb.net connection string references.
pl-0-us-east-1-k45tj.mongodb.net is the hostname for each node in one Atlas cluster in one region for which you have configured AWS PrivateLink.
1024, 1025, and 1026 are unique ports that Atlas assigns on the load balancer for each Atlas replica set node in the region for which you enabled AWS PrivateLink. All nodes in an Atlas replica set are accessible via the same hostname, with the load balancer resolving individual nodes by their unique port.

Hostname DNS Resolution in Private Endpoint-Aware Connection Strings and SRV Records

The hostname in the SRV record and the standard connection string is a DNS Canonical Name (CNAME) record that resolves to the endpoint-specific regional DNS name that AWS generates for the interface endpoint. A DNS ALIAS record exists for each subnet in your VPC that you deployed the interface endpoint to. Each ALIAS record contains the private IP address of the interface endpoint for that subnet.

The following example shows the DNS lookup for the hostname in the SRV record and in the standard connection string, including the endpoint-specific regional DNS name for the interface endpoint and its DNS ALIAS records:

$ nslookup pl-0-us-east-1-k45tj.mongodb.net
Server: 127.0.0.53
Address: 127.0.0.53#53
Non-authoritative answer:
pl-0-us-east-1-k45tj.mongodb.net
canonical name = vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com.
Name: vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com
Address: 10.0.30.194
Name: vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com
Address: 10.0.20.54

Multi-Region Private Endpoints

Private endpoints are only available in multi-region clusters if there is a node within each region that the cluster spans that has a private endpoint configured. To learn more about configuring multi-region private endpoints, see Regionalized Private Endpoints for Multi-Region Sharded Clusters.

Test Connectivity from Your Deployed Application

You can use the tools nslookup and telnet to test the connectivity from your application to your Private Endpoint in Atlas.

Get the connection details for your Atlas cluster.

Run nslookup with the -type=SRV flag to get the port numbers associated with each of the nodes in your cluster.

 nslookup -type=SRV _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net

 Server: 127.0.0.53
 Address: 127.0.0.53#53
 Non-authoritative answer:
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1026 pl-0-us-east-1-k45tj.mongodb.net.
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1024 pl-0-us-east-1-k45tj.mongodb.net.
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1025 pl-0-us-east-1-k45tj.mongodb.net.

Test the connectivity.

From your application environment, with one of the listed ports (for example, 1026, 1024 or 1025 in the example output above), run the following telnet command to test connectivity:

telnet pl-0-<xyz>.mongodb.net 1024
telnet pl-0-<xyz>.mongodb.net 1025
telnet pl-0-<xyz>.mongodb.net 1026

To view the status of each private endpoint:

In Atlas, go to the Network Access page for your project.

If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
If it's not already displayed, select your project from the Projects menu in the navigation bar.
In the sidebar, click Network Access under the Security heading.
The Network Access page displays.

Click the Private Endpoint tab.

Review the statuses.

The Atlas Endpoint Service Status and Endpoint Status fields show the status of each private endpoint.

Refer to the following statuses to help you determine the state of your private endpoint connections:

Atlas Endpoint Service Status

Status	Description
Creating private link	Atlas is creating the load balancer and VNet resources.
Failed	A system failure has occurred.
Available	Atlas created the load balancer and Azure Private Link Service. The Azure Private Link Service is ready to receive connection requests.
Deleting	Atlas is deleting the Azure Private Link Service.

Endpoint Status

Status	Description
Not configured	Atlas created the load balancer and Azure Private Link Service, but you haven't created a private endpoint yet. Click Edit and complete the wizard to create the private endpoint.
Initiating	Atlas has not yet accepted the connection to your private endpoint.
Failed	Azure failed to establish a connection between Atlas VNet resources and the private endpoint in your VNet. Click Edit, verify that the information you provided is correct, and then create the private endpoint again.
Available	Atlas VNet resources are connected to the private endpoint in your VNet. You can connect to Atlas clusters in this region using Azure Private Link.
Deleting	Atlas is removing the private endpoint connection from the Azure Private Link Service.

Obtain Private IPs with DNS Lookup

When a client in your VNet connects to an Atlas cluster using one of these private endpoint-aware connection strings, the client attempts to establish a connection to the Private Link Service in the Atlas VNet through the private endpoint's network interface. The Private Link service sends traffic through an Azure Standard Load Balancer to the Atlas cluster nodes that you deployed in that region. Your client's DNS resolution mechanism handles resolving the hostname to the network interface's private IP address. The driver is only aware of the hostname in the connection string, listening on one port for each node in the cluster's replica set.

SRV Record for DNS Seedlist Private Endpoint-Aware Connection Strings

The following example shows the SRV record for an Azure Private Link-enabled single-region cluster, showing three unique ports defined for pl-0-eastus2.uzgh6.mongodb.net:

$ nslookup -type=SRV _mongodb._tcp.cluster0-pl-0.uzgh6.mongodb.net
Server:  127.0.0.53
Address:  127.0.0.53#53
Non-authoritative answer:
_mongodb._tcp.cluster0-pl-0.uzgh6.mongodb.net service = 0 0 1024 pl-0-eastus2.uzgh6.mongodb.net.
_mongodb._tcp.cluster0-pl-0.uzgh6.mongodb.net service = 0 0 1025 pl-0-eastus2.uzgh6.mongodb.net.
_mongodb._tcp.cluster0-pl-0.uzgh6.mongodb.net service = 0 0 1026 pl-0-eastus2.uzgh6.mongodb.net.

In the preceding example:

_mongodb._tcp.cluster0-pl-0.uzgh6.mongodb.net is the SRV record that the connection string references.
pl-0-eastus2.uzgh6.mongodb.net is the hostname for each node in one Atlas cluster in one region for which you have configured Azure Private Link.
1024, 1025, and 1026 are unique ports that Atlas assigns on the load balancer for each Atlas replica set node in the region for which you enabled Azure Private Link. All nodes in an Atlas replica set are accessible via the same hostname, with the load balancer resolving individual nodes by their unique port.

Hostname DNS Resolution in Private Endpoint-Aware Connection Strings and SRV Records

The hostname in the SRV record and the standard connection string is a DNS A record that resolves to the private IP address of the private endpoint's network interface.

The following example shows the DNS lookup for the hostname in the SRV record and in the standard connection string:

$ nslookup pl-0-eastus2.uzgh6.mongodb.net
Server:  127.0.0.53
Address:  127.0.0.53#53
Non-authoritative answer:
Name:  pl-0-eastus2.uzgh6.mongodb.net
Address: 10.0.0.4

Multi-Region Private Endpoints

Test Connectivity from Your Deployed Application

You can use the tools nslookup and telnet to test the connectivity from your application to your Private Endpoint in Atlas.

Get the connection details for your Atlas cluster.

Run nslookup with the -type=SRV flag to get the port numbers associated with each of the nodes in your cluster.

 nslookup -type=SRV _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net

 Server: 127.0.0.53
 Address: 127.0.0.53#53
 Non-authoritative answer:
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1026 pl-0-us-east-1-k45tj.mongodb.net.
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1024 pl-0-us-east-1-k45tj.mongodb.net.
 _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1025 pl-0-us-east-1-k45tj.mongodb.net.

Test the connectivity.

From your application environment, with one of the listed ports (for example, 1026, 1024 or 1025 in the example output above), run the following telnet command to test connectivity:

telnet pl-0-<xyz>.mongodb.net 1024
telnet pl-0-<xyz>.mongodb.net 1025
telnet pl-0-<xyz>.mongodb.net 1026

To view the status of each private endpoint:

In Atlas, go to the Network Access page for your project.

If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
If it's not already displayed, select your project from the Projects menu in the navigation bar.
In the sidebar, click Network Access under the Security heading.
The Network Access page displays.

Click the Private Endpoint tab.

Review the statuses.

The Atlas Endpoint Service Status and Endpoint Status fields show the status of each private endpoint.

Refer to the following statuses to help you determine the state of your private endpoint connections:

Atlas Endpoint Service Status

Status	Description
Creating private link	Atlas is creating the network load balancer and VPC resources.
Failed	A system failure has occurred.
Available	Atlas created the network load balancer and VPC endpoint service. The private endpoint service is ready to receive connection requests.
Deleting	Atlas is deleting the private endpoint service.

Endpoint Status

Status	Description
Initiating	Atlas is not yet connected to your private endpoint and has not yet accepted the endpoints.
Waiting for User	VPC resources on Atlas are ready for use. You must set up the endpoints within your VPC by running the shell script.
Verified	Atlas verified the endpoints within your VPC but has not yet accepted the private endpoint in your Google Cloud VPC. It might take several minutes for the Endpoint Status to become `Available`.
Available	The Atlas VPC resources are connected to the private endpoint in your Google Cloud VPC. Atlas has accepted the endpoints. You can connect to Atlas clusters in this region using GCP Private Service Connect.
Active	Atlas is ready to use VPC resources. Atlas has accepted the endpoints. A VM is assigned to the private service connection.
Failed	Google Cloud failed to establish a connection between Atlas VPC resources and the private endpoint in your Google Cloud VPC. Click Edit, verify that the information you provided is correct, and then create the private endpoint again.
Deleted	You manually deleted the private endpoint from a region in Atlas. You must also delete the private endpoint in Google Cloud to delete resources. Pending deletion of the region group.

Multi-Region Private Endpoints

Test Connectivity from Your Deployed Application

You can use the tools nslookup and telnet to test the connectivity from your application to your Private Endpoint in Atlas.

Get the connection details for your Atlas cluster.

Run nslookup with the -type=SRV flag to get the port numbers associated with each of the nodes in your cluster.

 nslookup -debug -type=SRV _mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net

Server:               8.8.8.8
Address:      8.8.8.8#53
------------
    QUESTIONS:
          _mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net, type = SRV, class = IN
    ANSWERS:
    ->  _mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net
    service = 0 0 27017 pl-00-000-us-central1-gcp.test.mongodb.net.
    ttl = 60
    ->  _mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net
          service = 0 0 27017 pl-00-001-us-central1-gcp.test.mongodb.net.
          ttl = 60
    ->  _mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net
          service = 0 0 27017 pl-00-002-us-central1-gcp.test.mongodb.net.
          ttl = 60
    AUTHORITY RECORDS:
    ADDITIONAL RECORDS:
------------
Non-authoritative answer:
_mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net     service = 0 0 27017 pl-00-000-us-central1-gcp.test.mongodb.net.
_mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net     service = 0 0 27017 pl-00-001-us-central1-gcp.test.mongodb.net.
_mongodb._tcp.gpc-mongo-pl-0-us-central1.test.mongodb.net     service = 0 0 27017 pl-00-002-us-central1-gcp.test.mongodb.net.

Test the connectivity.

From your application environment, with one of the listed ports (for example, 27017 in the example output above), run the following telnet command to test connectivity:

telnet pl-0-<xyz>.mongodb.net 27017

Back

Manage and Connect

Cloud Provider Access