All Products
Search

This Product

    PolarDB:Troubleshoot issues related to an IP whitelist

    Document Center

    PolarDB:Troubleshoot issues related to an IP whitelist

    Last Updated:Mar 28, 2026

    An incorrectly configured IP whitelist is a common cause of database connection failures in PolarDB. This guide helps you confirm whether the IP whitelist is the cause and fix the configuration.

    Confirm the IP whitelist is the issue

    Before investigating whitelist scenarios, verify that the problem originates from the whitelist. Use Telnet to connect to the cluster endpoint. A successful Telnet connection displays the MySQL handshake message with a version number (such as 5.7.32), as shown in the following figure:

    图1.png

    If the client receives the handshake message, the IP whitelist is correctly configured. If the handshake message does not appear, the whitelist is misconfigured. See Configure an IP whitelist to correct it.

    You can also use the primary IP address to test connectivity. If the connection via the primary IP address fails, the issue is in the IP whitelist. Use Telnet or tcpdump to continue troubleshooting.

    Failure scenarios

    Incorrectly configured public VIPs of an Enterprise Edition cluster

    When you access a public virtual IP address (VIP) of an Enterprise Edition cluster using Telnet and the connection fails, you see the following:

    图2.png

    When you capture packets on the client side, the SYN message from the first step of the TCP three-way handshake continues to be sent.

    Incorrectly configured VPC endpoint or public endpoint

    This scenario applies to:

    • The VPC endpoint of an Enterprise Edition cluster

    • The public endpoint or VPC endpoint of a Standard Edition cluster

    When you connect to these endpoints using Telnet, the connection appears to establish, but the client never receives the MySQL handshake message:

    6C37AC08-B74B-475e-83CB-5E99EFD78F0B.png

    When you capture packets on the client side, the SYN and ACK messages in the second step and the ACK message in the third step of TCP three-way handshake continue to wait for a response.

    Solution

    1. Temporarily add the CIDR block 0.0.0.0/0 to the IP whitelist.

    2. Test the connection. If the database becomes accessible, the IP whitelist was misconfigured.

    3. Identify the correct IP addresses for your clients and add them to the whitelist.

    4. Remove 0.0.0.0/0 from the whitelist.

    For steps on updating the whitelist, see Configure an IP whitelist.