emqx Files

Enhancements

Core MQTT Functionalities

• #15773 Throttled client ID registration during reconnects.
• When a previous session cleanup is still in progress, new connections using the same client ID are now throttled. This prevents instability when clients reconnect aggressively.
• Affected clients receive reason code 137 (Server Busy) in the CONNACK with Reason-String "THROTTLED", and should retry after the cleanup completes.
• Fixed the reason code returned when another connection registers the same client ID; now correctly returns 137 instead of 133.

Data Integration

• #15542 Upgraded our erlcloud library to 3.8.3.0. This allows one to set up a S3 Connector without specifying Access Key Id and Secret Access Key, so long as the EC2 instance EMQX is running in has the correct IAM permissions to read/write to the configured bucket(s).

• #15585 Updated the brod client to version 4.4.4, expanding support for a wider range of Kafka APIs. This update addresses the deprecation of JoinGroups API versions v0 - v1.

• #15845 The static_clientids configuration for the MQTT Connector now supports specifying a username and password for each client ID. This is particularly useful for scenarios like connecting to Azure IoT Hub, where each device (client ID) requires a unique set of credentials. This enhancement helps ensure successful connections across multiple nodes in a clustered environment.

• #15911 The HTTP request timeout for the HTTP Action is now configurable via the resource_opts.request_ttl setting. Previously, this timeout was fixed at 30 seconds and could not be adjusted.

Observability

• #15499 Added a force deactivate alarm API endpoint to allow administrators to forcibly deactivate active alarms.

• #15944 Improved the information returned when a resource is marked as disconnected for the following Connectors: LDAP, Syskeeper, IoTDB, Snowflake (aggregated), JWKS Authentication.

Performance

• #15536 Disable the node.global_gc_interval configuration by default.

• #15539 Optimized Erlang VM parameters to improve performance and stability:

• Increased buffer size for distributed channels to 32 MB (+zdbbl 32768) to prevent busy_dist_port alarms during intensive Mnesia operations.

• Disabled scheduler busy-waiting (+sbwt none +sbwtdcpu none +sbwtdio none) to lower CPU usage reported by the operating system.

• Set scheduler binding type to db (+stbt db) to reduce message latency.

• #15907 Improve system memory usage.

• Authorization (authz) cache is now cleared immediately when a client disconnects, reducing unnecessary memory consumption.

• Fields such as client ID, username, password, and topic are copied into new binaries (when more than 64 bytes) instead of being slices from the raw packet to reduce 'binary' part of memory usage in Erlang VM.

• #15949 Changed the default value of the parse_unit option in listener configuration from chunk to frame. This change can significantly reduce CPU usage when the payload size exceeds the socket buffer (default is 4 KB).

Note: With parse_unit = frame, if a PUBLISH packet exceeds the maximum allowed size, EMQX will close the connection instead of sending a DISCONNECT packet.

• #16165 Optimized the performance of the GET /clients_v2 API. Previously, when the cluster had around 50,000 clients or more, API calls to retrieve the client list could be extremely slow or even time out.

Bug Fixes

Core MQTT Functionalities

• #15884 Resolved an issue where, in rare cases, the global routing table could indefinitely retain routing information for nodes that had long left the cluster.

• #15518 Resolved a race condition that may lead to accumulating inconsistencies in the routing table and shared subscriptions state in the cluster when a large number of shared subscribers disconnect simultaneously.

• #15872 Eliminated warning log unclean_terminate when disconnected after CONNACK is sent with a non-zero reason code.

Deployment

• #15553 Fixed an issue in the Helm chart where deploying EMQX with default values started multiple replicas and caused all nodes except one to crash. The chart now defaults to a single replica, since clustered deployments require an Commercial License.

• #15580 Added a new emqxLicenseSecretRef variable to the EMQX Enterprise Helm chart. This allows users to specify a Kubernetes Secret containing the EMQX license key, so the license is applied automatically.

This replaces the non-functional emqxLicenseSecretName variable, which created and mounted a secret file but did not pass the license to EMQX.

• #15712 Fixed node boot-up failure during rolling upgrade from older versions (before 5.9)

In previous EMQX versions (before 5.9), a bug in the ZIP timestamp encoder could store an invalid “seconds” value in archive entries (values corresponding to the 30th or 31st 2-second slot in DOS time format).

• #15863 Fixed the license quota alarm message to correctly reflect session quotas instead of live connections.

Security

• #15581 Upgraded Erlang/OTP version from 26.2.5.2 to 26.2.5.14. This upgrade includes two TLS-related fixes from OTP that affect EMQX:
• Fixed a crash in TLS connections caused by a race condition during certificate renewal.

• Added support for RSA certificates signed with RSASSA-PSS parameters. Previously, such certificates could cause TLS handshakes to fail with a bad_certificate / invalid_signature error.

• #16237 Fixed an issue where OIDC SSO–related logs might still be printed even after SSO was disabled.

• #16217 Fixed an issue where the OIDC login callback could fail to locate the user session in multi-node cluster environments.

Access Control

• #15818 Corrected handling of {allow|deny, all} ACL rules.

Previously, these rules were internally translated to match #, which incorrectly failed to match topics prefixed with $ (e.g. $testtopic/1) due to MQTT spec restrictions. Now, a special internal value is used to ensure {allow|deny, all} rules correctly match any topic, including $-prefixed ones.

• #15844 Added validation to forbid adding empty usernames to the built-in database authenticator. Such users cannot be deleted via the HTTP API later, since they mess up the API path.

If you have such an user and wish to delete it, run the following in an EMQX console:

erlang mria:transaction(emqx_authn_shard, fun() -> mnesia:delete(emqx_authn_mnesia, {'mqtt:global',<<>>}, write) end).

• #15899 Improved memory management by ensuring that the authorization (authz) cache is cleared immediately when a client disconnects, reducing unnecessary memory consumption.

• #16081 Fixed an issue where clients using extended authentication and memory-based sessions could crash with a session_stepdown_request_exception caused by a calling_self error.

Example error log

``` 2025-09-24T07:13:08.973954+08:00 [error] clientid: someclientid, msg: session_stepdown_request_exception, peername: 127.0.0.1:41782, username: admin, error: exit, reason: calling_self, stacktrace: [{gen_server,call,3,[{file,"gen_server.erl"},{line,1222}]},{emqx_cm,request_stepdown,4,[{file,"emqx_cm.erl"},{line,427}]},{emqx_cm,do_takeover_begin,2,[{file,"emqx_cm.erl"},{line,398}]},{emqx_cm,takeover_session,2,[{file,"emqx_cm.erl"},{line,384}]},{emqx_cm,takeover_session_begin,2,[{file,"emqx_cm.erl"},{line,305}]},{emqx_session_mem,open,4,[{file,"emqx_session_mem.erl"},{line,210}]},{emqx_session,open,3,[{file,"emqx_session.erl"},{line,263}]},{emqx_cm,'-open_session/4-fun-1-',4,[{file,"emqx_cm.erl"},{line,290}]},{emqx_cm_locker,trans,2,[{file,"emqx_cm_locker.erl"},{line,32}]},{emqx_channel,post_process_connect,2,[{file,"emqx_channel.erl"},{line,575}]},{emqx_connection,with_channel,3,[{file,"emqx_connection.erl"},{line,852}]},{emqx_connection,process_msg,2,[{file,"emqx_connection.erl"},{line,470}]},{emqx_connection,process_msgs,2,[{file,"emqx_connection.erl"},{line,462}]},{emqx_connection,handle_recv,3,[{file,"emqx_connection.erl"},{line,406}]},{proc_lib,wake_up,3,[{file,"proc_lib.erl"},{line,340}]}], action: {takeover,'begin'}, ... ```

Data Integration

• #15616 Kafka connections are now considered healthy even if a topic_authorization_failed error is returned for the default probing topic.

• #15826 Improved Kafka consumer connector health check behavior with restricted ACLs. Previously, Kafka Consumer Connector health checks could fail if the configured user lacked permission to access the internal ____emqx_consumer_probe consumer group used for the check. With this fix, if the Kafka broker returns an "ACL denied" response, EMQX will treat the connection as healthy.

• #15827 Fixed atom and process leaks in the GreptimeDB driver.

Fixed a function_clause error that could arise if certain incorrect write syntaxes were used in GreptimeDB Actions.

• #15836 Enriched the returned information when a Kafka Consumer Source fails to be added, for example, due to denied topic ACLs.

• #15850 Fixed an issue where the MQTT bridge incorrectly showed a stale connection as Connected, and failed to re-establish the connection.

• #15866 Upgraded Kafka producer lib wollf to 4.0.12 to improve handling of temporarily missing partitions in Kafka metadata responses.

In rare race conditions, Kafka may return an incomplete partition list. Previously, this was only handled when a topic was recreated with fewer partitions, but not when partitions were temporarily missing. This gap could cause the partition producer to stall and block shutdown indefinitely.

• #15906 Upgraded Kafka producer library Wolff from 4.0.12 to 4.0.13, which adds handling for the record_list_too_large error in ProduceResponse.

• #15902 Upgraded MQTT client library to 1.13.8. This improves MQTT bridge connectivity with:

• Connector will automatically reconnect when peer broker does not reply PINGRESP.

• Bridge over TLS failure is more promptly handled if connection breaks while waiting for CONNACK.

• #15910 Fixed an issue with Connectors where a pool of workers could fail to recover from a failure if multiple workers crashed simultaneously in large worker pools.

Connectors affected and fixed:

• MySQL
• PostgreSQL
• Oracle
• SQLServer
• TDEngine
• Cassandra
• Dynamo
• HTTP
• Couchbase
• GCP PubSub
• Snowflake

Upgraded gun and related dependencies to 2.1.0.

• #16010 Fixed an issue where a Republish Fallback Action could fail with a function_clause error if the originating rule's SQL did not include the metadata field from the rule environment.

Example error log:

[error] tag: RESOURCE, msg: failed_to_trigger_fallback_action, reason: {error,function_clause}, fallback_kind: republish, primary_action_resource_id: <<"action:type:name:connector:type:name">>, republish_topic: <<"republish/topic">>

• #16043 Improved log details for Kafka data integration when not_all_kafka_partitions_connected event occurs.

• #16046 Fixed a potential out-of-memory (OOM) crash when loading or restarting a configuration containing a Connector with several hundred Actions.

• #16138 Fixed a Redis cluster failover issue that could cause the Connector to remain stuck in a "connecting" state.

Previously, EMQX’s Redis cluster client only refreshed the cluster topology when regular queries (such as GET) failed. However, failures in periodic PING commands did not trigger a refresh. As a result, after a failover, the connector could continue using the outdated cluster topology if no other commands were issued, preventing recovery.

With this fix, failed PING responses now trigger a cluster topology refresh, ensuring that the connector can detect failovers and recover promptly.

Rule Engine

• #16028 Fixed rule engine jq function memory leak.

Previously if jq built-in function index is used (e.g. .key | index("name")), it would result in memory leak.

Smart Data Hub

• #15706 Fixed an indexing issue that could cause Message Transformations and Schema Validations to behave inconsistently. Deleting one item could corrupt the topic index, so that a subsequent item remained active even after being disabled.

• #15708 Fixed an issue where external schema registries were not reloaded after a node restart.

• #15810 Introduced spb_{en,de}code functions to correct handling of bytes_value Metrics. Fixed an issue with the original sparkplug_{en,de}code functions, which did not base64 encode/decode bytes_value metric values as required by the Protobuf specification. To address this, new spb_{en,de}code functions have been introduced for correct encoding/decoding of such fields. The old sparkplug_{en,de}code functions are now deprecated to maintain backward compatibility.

Observability

• #15639 Fixed incorrect counting of the packets.subscribe.auth_error metric.

• #15785 Resolved a crash that occurred when MQTT usernames containing non-ASCII characters were used in formatting network congestion alarm messages.

• #15963 Reduced excessive audit log entries generated during looped evaluations in the remote shell (remsh).

• #15967 Fixed an issue where Mnesia transaction blocking during the cleanup of large volumes of audit logs could lead to rapid memory growth.

Gateway

• #15679 Fixed incorrect global chain names for the ExProto, JT/T 808, GB/T 32960, and OCPP gateways. Built-in authentication data for these gateways was previously grouped under unknown:global, causing conflicts between gateways.

• #15699 Fixed an issue where built-in authentication data for gateways (e.g., CoAP) was incorrectly removed when a node was stopped or restarted.

• #15822 Fixed an issue where the OCPP connection would crash after sending a certain number of messages.

Rate Limit

• #15794 Improved the behavior of connection rate limit updates to ensure that changes (e.g., to burst rate or rate thresholds) are applied immediately after the listener configuration is updated. Previously, parts of the internal limiter state were not refreshed correctly, which could result in rate limits appearing stricter than configured.

ExHook

• #15683 Fixed ExHook TLS options so that gRPC clients can correctly verify the server hostname during the TLS handshake.

Breaking Changes

• #15753 Listener connection rate limits (max_conn_rate and max_conn_burst) are now enforced per listener rather than per acceptor, restoring the behavior before 5.9.0.

As a result, configurations from versions 5.9.0 and 5.9.1 are incompatible: the specified rate values must be scaled up by the number of acceptors configured for each listener to preserve the same effective limits.

• #16062 Fixed an issue where RocketMQ actions ignored the configured payload template and sent the entire rule output instead.

If you relied on the previous (incorrect) behavior, you may need to update your payload templates to ensure messages are formatted as expected.

• #16284 Stopped releasing packages for macOS 13 and CentOS 7.