Client Banned for Connection Flapping Alert

The Client Banned for Connection Flapping alert indicates that EMQX Cloud activated its default flapping protection. When a client repeatedly connects and disconnects at a high rate, for example, during an abnormal reconnection storm or malicious connection attempts, EMQX Cloud automatically adds its Client ID to the blacklist to protect broker stability.

• Default rule: A Client ID is added to the blacklist after more than 120 connection attempts within one minute. It remains blocked for 60 minutes and cannot reconnect to the protected deployment during that period.
• Manual recovery: If the behavior is legitimate, go to Access Control -> Blacklist and remove the Client ID manually.

Client ID Conflict and Short Reconnection Interval

Symptom

When two or more clients use the same Client ID, they compete for a single online connection. If the client SDK also uses a very short reconnection interval, such as 100 ms, the clients can enter a rapid connect, disconnect, and reconnect loop that triggers flapping protection.

In Deployment Logs, the same Client ID repeatedly appears in flapping-related entries while its source IP address (peername) changes. Client logs may also show connections that are immediately closed or taken over.

Common Causes

• Multiple clients use the same Client ID.
• The automatic reconnection interval is too short and has no backoff.
• A copied configuration or image assigns the same Client ID to multiple devices.

Resolution

• Assign a globally unique Client ID, such as a device serial number, user ID, or persistent UUID, to each client.
• Use exponential backoff, for example, 1, 2, and 4 seconds, and add jitter.
• Check for copied configurations or images that cause multiple clients to share a Client ID.

Frequent Disconnections Due to Poor Network Quality

Symptom

On a mobile, weak, unstable, or lossy network, a client may repeatedly disconnect after keepalive failures and reconnect immediately, triggering flapping protection.

In this case, the client's peername or IP address usually remains stable, while disconnections are concentrated on a particular network egress or time period. Client or gateway logs may contain timeouts, connection resets, or TLS handshake failures. Monitoring charts may show volatile connection counts and frequent disconnections.

Common Causes

• An unstable network link or regional network problem.
• NAT or firewall idle connection timeouts.
• Packet loss that causes keepalive checks to fail.

Resolution

• Set appropriate client keepalive and timeout values to avoid false failure detection.
• Investigate NAT timeouts, load balancer idle connection policies, QoS, and ACL-related packet loss.
• Configure reconnection backoff to prevent reconnection storms during network instability.

Client Application Failure

Symptom

A client application defect, such as incorrect connection logic or multiple threads or processes creating connections, causes many connection attempts from the same Client ID.

Logs from one device or process show concurrent connection attempts at a rate far above normal, without a strong correlation to network conditions.

Common Causes

• Client code creates duplicate connections.
• Multiple threads or processes use the same Client ID.
• Failed connections enter an unlimited rapid retry loop.

Resolution

• Add synchronization on the client so that only one connection loop uses a Client ID at a time.
• Limit the retry rate and use backoff after connection failures.
• For critical errors such as authentication failures, authorization failures, or invalid parameters, stop rapid retries and report the error first.

Troubleshooting

1. Log in to the EMQX Cloud Console, open Deployment Logs, and set Error Type to Clients. Record the clientid, peername (IP:port), username if present, and timestamps.

2. Go to Monitor -> Alerts -> Alert List and check for the Client Banned for Connection Flapping alert.

3. Go to Monitor -> Clients, search for the Client ID, and review its connection state and recent behavior, including frequent connections and disconnections or source IP changes.

4. Go to Access Control -> Blacklist and check whether the Client ID is listed and how much time to live (TTL) remains. If legitimate traffic was blocked by an incorrect configuration, remove the entry to restore service, then correct the root cause such as duplicate Client IDs or missing reconnection backoff.

5. Classify the issue based on the evidence:

   • If different connections repeatedly take over the same Client ID, investigate a Client ID conflict.
   • If the issue is concentrated on a specific network or egress, investigate poor network quality.
   • If the issue affects only a particular client version or device model, investigate a client application failure.

Monitoring and Statistics

On Monitor -> Alerts, review the alert frequency. Compare it with Deployment Logs and the Monitor timeline to determine whether the issue affects one client or many clients.

For long-term analysis, record client events through data integration. You can then:

• Count connect and disconnect events for each Client ID within a specified interval.
• Identify the Client IDs and source IP addresses that most frequently trigger a ban in an external storage or analytics system.

Flapping Protection Recommendations

• Do not use extremely short reconnection intervals, such as 100 ms, in production. On weak or unstable networks, they can cause reconnection storms and place clients on the blacklist.
• If the application requires several reconnection attempts within a short period, use exponential backoff with jitter.
• To adjust flapping protection thresholds or policies, use the settings available in the Console or contact EMQX Technical Support for an assessment.