Skip to content

feat: list common disconnect reasons #3111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: release-6.0
Choose a base branch
from
Open

feat: list common disconnect reasons #3111

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
216fa94
feat: list common disconnect reasons
thalesmg Aug 7, 2025
afa44c4
chore: improve descriptions
thalesmg Aug 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 32 additions & 4 deletions en_US/admin/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,9 @@ Loaded 'Mod' module on []: ok

## conf cluster_sync

This command is mostly for troubleshooting when there is something wrong with cluster-calls used to sync configuration changes between the nodes in the cluster.
This command is mostly for troubleshooting when there is something wrong with cluster-calls used to sync configuration changes between the nodes in the cluster.

::: tip
::: tip

In EMQX 5.0.x, this command was named `cluster_call`. This old command is still available in EMQX 5.1 but it is not displayed in the help information.

Expand Down Expand Up @@ -704,7 +704,7 @@ This command is like the `trace` command, but applies on all nodes in the cluste

## traces

This command is similar to the `trace` command, but it starts or stops a tracer across all nodes in the cluster.
This command is similar to the `trace` command, but it starts or stops a tracer across all nodes in the cluster.

| Command | Description |
| ------------------------------------------------------- | --------------------------------- |
Expand Down Expand Up @@ -787,6 +787,7 @@ tcp:default
running : true
current_conn : 12
max_conns : 5000000
shutdown_count : [{takenover,2},{discarded,1}]
ws:default
listen_on : 0.0.0.0:8083
acceptors : 16
Expand All @@ -803,6 +804,33 @@ wss:default
max_conns : 5000000
```

#### Common shutdown reasons

| Reason | Description |
|-------------------------------|-------------------------------------------------------------------------------------------------------|
| `banned` | The client is blacklisted due to ACL violations, rate limiting, or IP restrictions. |
| `closed` | The connection was closed either by the server or the client. |
| `discarded` | A client with the same clientid connected with `clean_start = true` while the old session was alive. |
| `takenover` | A client with the same clientid connected with `clean_start = false` while the old session was alive. |
| `einval` | Invalid argument or socket error, happens when EMQX tries to write data to a socket which is closed already by the system (a race condition between socket state change notification and data write). |
| `frame_too_large` | The MQTT packet exceeds the maximum allowed frame size. |
| `idle_timeout` | The `CONNECT` packet is not received for too long after the configured timeout after connection is established. |
| `invalid_proto_name` | The protocol name in the `CONNECT` packet is invalid or not `"MQTT"`. |
| `invalid_topic` | The client used an invalid topic (e.g., containing illegal characters or forbidden by the broker). |
| `keepalive_timeout` | The client failed to send any packets within the keepalive interval. |
| `malformed_packet` | The MQTT packet is corrupted or does not conform to the MQTT specification. |
| `not_authorized` | The client attempted an unauthorized action, rejected by ACL. |
| `ssl_closed` | The SSL/TLS connection was closed by the peer. |
| `ssl_error` | A SSL/TLS handshake or data transmission error occurred. |
| `ssl_upgrade_timeout` | Timeout during SSL/TLS handshake. |
| `unexpected_packet` | The client sent a packet that was unexpected in the current connection state. |
| `zero_remaining_len` | The packet has a zero remaining length field, which is invalid in most contexts. |
| `bad_username_or_password` | The client's credentials failed authentication. |
| `client_identifier_not_valid` | The client ID is being registered by another connection. |
| `protocol_error` | A generic MQTT protocol violation. |
| `tcp_closed` | The TCP connection was closed by the client or network layer. |
| `timeout` | A general timeout occurred (e.g., during authentication, etc.). |

### listeners stop \<Identifier\>

```bash
Expand Down Expand Up @@ -832,7 +860,7 @@ Restarted tcp:default listener successfully.
Restarting a listener causes all the connected clients to disconnect.
:::

### listeners enable \<Identifier\> <true/false>
### listeners enable \<Identifier\> <true/false>

```bash
$ emqx ctl listeners enable tcp:default true
Expand Down