emqx Files

Enhancements

AI Interoperability

• #16840 Implemented Agent-to-Agent (A2A) Card Registry. This feature enables autonomous AI agents to discover and collaborate through a standardized, event-driven MQTT 5.0 mechanism.

• #16958 Added focused /api-spec.md endpoint and /api-spec.html to support drill-down discovery of EMQX HTTP API context, especially for AI agents and other tools that benefit from fetching only the relevant API slices instead of a single bloated spec.

Core MQTT Functionalities

• #16612 Introduced the emqx_setopts app for $SETOPTS server-side option updates, including keepalive control topics and warning+suppression for unknown $SETOPTS/* publishes.

• #16887 Added optional MQTT subscription message filters controlled by mqtt.subscription_message_filter.

When enabled, clients can subscribe with a ? suffix such as sensor/+/temperature?location=roomA&value>25 and EMQX will deliver only the messages whose MQTT 5 User-Property entries satisfy the filter expression. When disabled, ? remains part of the topic filter text and no extra filtering is applied.

Messages dropped by subscription-filter mismatch are reported through the existing delivery.dropped event with reason subscription_filter and counted by the new delivery.dropped.filter metric.

• #16929 Two new limiter kinds are introduced: delivery_messages and delivery_bytes. In contrast to the existing messages and bytes limiters, which limit messages published by a single client, the new limiter throttle messages received by a single client from any source. If the limit is hit, QoS 0 messages are dropped, QoS > 0 are queued internally, and a retry is scheduled. The retry time is derived from the limiter's configuration.

The new limiters are only supported for memory sessions (durable_sessions.enable = false).

If unspecified, the default values are unlimited, thus keeping backwards compatibility.

• #16779 Improved handling of malformed first packets by classifying them as invalid CONNECT packets and adding better protocol hints in logs.

Data Integration

• #16589 Updated jq library used in the Rule Engine runtime to version 1.8.1.

Note that the jq 1.8.1 language contains several subtle breaking changes compared to 1.6.1.

• Providing empty string as jq program is now considered an error: use "." instead. (jq#2790)
• String functions now use code point indices: indices/1, index/1, and rindex/1 functions now use code point indices instead of byte indices; use utf8bytelength/0 to get byte index if needed. (jq#3065)
• tonumber/0 rejects numbers with leading or trailing whitespace: use trim/0 before calling tonumber/0. (jq#3055, jq#3195)
• last(empty) behavior changed: last(empty) now yields no output values, consistent with first(empty). (jq#3179)
• limit/2 errors on negative count, instead of silently accepting it. (jq#3181)
• Tcl-style multiline comments supported: this may subtly affect parsing of existing code. (jq#2989)
• Decimal number conversion changed: decimal numbers are now converted to binary64 (double) instead of decimal64. (jq#2949)
• nth/2 emits empty on index out of range, instead of erroring. (jq#2674)

• String multiplication by 0 or less than 1 now emits an empty string instead of the original string. (jq#2142)

• #16634 Added support for GET requests in external HTTP schema validation by allowing schema registry entries to specify the HTTP method (POST remains the default).

• #16647 Now, in GreptimeDB and EMQX Tables Actions, integer values that are not suffixed with i or u are automatically cast to float (float64) values before being sent to the database.

In InfluxDB Write Syntax, float is the default numeric type, and integers must be annotated. Previously, when EMQX encountered a non-annotated integer, it would interpret it as a one-character string, and insertion would fail if the column was of type float.

• #16707 Added a Data Integration to consume from and publish messages to Azure Event Grid.

• #16750 Added support for using Workload Identity Federation (WIF) authentication with GCP Connectors (GCP PubSub Producer and Consumer, BigQuery), via Service Account Impersonation. At this point, only OIDC workload identity pool providers using Client Credentials grant type are supported.

• #16773 Now, when using MQTT Connector with SSL enabled, if unset, the Server Name Indication (SNI) field will be automatically filled with the server's hostname.

• #16893 Added a new Connector and Action that appends data to QuasarDB.

• #16962 Improved Kafka source polling behavior by ensuring fetch requests wait briefly for data instead of returning empty batches immediately when no records are available. This reduces unnecessary polling delays and helps Kafka consumers receive new records more consistently.

Access Control

• #16597 In MySQL and PostgreSQL authentication and authorization, improved the handling of unallowed and quoted variables in the SQL template.

• #16616 Added new configurations to SSO OIDC backend to allow specifying jq expressions to extract the desired role and namespace when creating new dashboard users.

• #16759 Added new functions timestamp_s and timestamp_ms to retrieve system time in variform expressions (used e.g. to populate additional client attributes on connection).

• #16817 Added REST API endpoints to reset authentication and authorization metrics counters.

• POST /authentication/:id/metrics/reset resets counters for a specific authenticator.

• POST /authorization/sources/:type/metrics/reset resets counters for a specific authorization source.

• #16849 Added cookie-based authentication fallback for plugin API endpoints.

Plugin UI iframes served by the dashboard can now authenticate via the emqx_auth cookie when no Authorization header is present. This only applies to /api/v5/plugin_api/... paths.

Management

• [#16958] Added emqx ctl api_keys CLI commands to list, show, add, delete, enable, and disable API keys from the command line.

Gateway

• #16734 Added ordered token, nkey, and jwt internal authentication methods to the NATS Gateway to reduce the authentication feature gap with NATS Server.

Deployment and Security

• #16653 Made Erlang distribution listener address configurable via node.dist_bind_address.

For example: node.dist_bind_address = "10.0.1.5".

Previously required configuration in vm.args as -kernel inet_dist_use_interface {10,0,1,5}.

• #16888 Refreshed the default TLS certificate bundle shipped with EMQX packages for local development and testing.

The new server certificate is issued for localhost and loopback addresses only (localhost, 127.0.0.1, ::1).

These default certificates are intended for test and local deployment scenarios only and must not be used in production.

• #16916 Now, the emqx_cert_expiry_at Prometheus metric takes into account the expiry date of certificates that belong to managed certificate bundles, when they are used in MQTT listeners.

Performance

• #16500 Optimize idle memory usage and reduce the cost of maintaining rate-based metrics.

Note that various 5-minute average rate metrics exposed via APIs are no longer exact averages over the last 300 samples, but are instead EWMAs (Exponentially Weighted Moving Averages) that approximate them closely.

• #16547 Disable TLS 1.2 session reuse by default to reduce TLS handshake overhead.

The TLS 1.2 session cache size is limited to 1000 entries, and the cache is local to each node.

This makes the reuse rate very low, especially when large numbers of connections connect to a large cluster.

• #16794 Enabled node-level authentication and authorization caches by default.

This reduces repeated backend lookups for repeated client checks out of the box, improving authentication and authorization performance in common deployments.

• #16829 Optimized the NATS gateway publish hot path to reduce per-message overhead in frame parsing, subject/topic handling, metrics updates, and ACK/message build steps.

• #16911 Reduce the overhead of Prometheus metrics collection by avoiding repeated queries of Mria statistics.

• #16550 Stop caching subscribe ACL check results.

MQTT subscription is mostly done once per connection life cycle. Holding the subscribe ACL check result in cache is most of the time a waste of RAM.

Bug Fixes

Core MQTT Functionalities

• #16721 Fixed QoS 2 duplicate handling when await_rel_timeout has expired.

Previously, if a client retried a QoS 2 PUBLISH with DUP=1 after the broker had expired the pending PUBREL state (default 300 seconds), the message could be published to subscribers again. EMQX now treats this retransmission as a duplicate handshake packet and returns PUBREC without re-delivering the application message.

• #16725 Disabled TCP connection congestion alarm by default by setting conn_congestion.enable_alarm = false in the default zone/global configuration.

• #16781 Fixed CONNECT validation when retained messages are unavailable.

When mqtt.retain_available is set to false, CONNECT packets with Will Retain set are now correctly rejected with CONNACK reason Retain not supported (0x9A).

• #16783 Fixed MQTT v5 SUBSCRIBE validation for Subscription-Identifier upper bound.

EMQX now accepts 268435455 (0x0FFFFFFF), which is the maximum valid Subscription Identifier value defined by the MQTT spec.

• #16974 In EMQX 6.1.1, when a session was subscribed to a topic filter containing retained messages and was later taken over or resumed without re-subscribing to the same topic filter, it would receive again the received messages. Now, the previous behavior is restored, meaning that, upon session resumption or takeover without explicit re-subscription, retained message iteration will cease.

• #16876 Changed log message msg_publish_not_allowed to msg_not_routed_to_subscribers.

Data Integration

• #16803 Improved error reporting when configuring batch operations for MySQL actions.

• #16796 Fixed handling of multiline SQL statements in connector actions.

• #16936 Fixed an issue where the health check of an Azure Blob Storage Action in aggregate mode could timeout if the container contained too many blobs.

• #16955 Eliminate Kafka producer action false health check warning logs.

Previously if Kafka producer is idling for too long, Kafka may close the connection (typically default is 10 minutes), if Kafka producer action health-checks happen to be performed around the same moment, there could be a false warning message with message "not_all_kafka_partitions_connected".

• #16972 HTTP and GCP PubSub Actions were patched to treat transient connection errors with reason closing as recoverable errors, reducing log noise.

• #16863 Added a warning log when an async reply is received for an already-expired request in async actions.

• #16847 Fixed a crash when non-ASCII unicode string is used in message transformation expression.

• #16979 MQTT ingress bridges now support consuming from remote message queues $queue/{name}/{bind-filter}.

• #16999 Fixed an issue where MQTT source failed to receive messages from $queue/ subscriptions when the remote broker has the Message Queue (mq) feature enabled. The MQ message delivery was missing the MQTT v5 Subscription-Identifier property in PUBLISH packets, which the MQTT bridge ingress relies on to route messages from queue subscriptions.

Access Control

• #16780 Fixed an issue in authorization source validation where requests missing the type field could trigger an internal error.

Now EMQX returns a clear BAD_REQUEST validation error for this case.

• #16805 Added support for authz hook results to opt out of authorization cache storage for dynamic ACL decisions.

• #16865 Added cert_common_name and cert_subject aliases for mqtt.client_attrs_init expressions, alongside the existing cn and dn variables.

• #16868 Improved REST API authentication error messages to guide programmatic clients toward using API keys (Basic auth) instead of repeatedly logging in for bearer tokens. Error responses now mention the api_key.bootstrap_file configuration option and the POST /api_key endpoint for creating persistent API keys.

• #16928 Dashboard-created REST API keys are now generated randomly instead of being derived from the API key name.

• #16939 Fixed the built-in database authenticator so it no longer logs a warning when the default bootstrap file path is configured but the file does not exist.

• #16993 Fixed an issue where an error response from an OIDC SSO provider would result in a 500 error. Now a more user-friendly result is returned.

Durable Storage

• #16874 Fixed a rare issue where Durable Storage backed by DS Raft could stop accepting new messages after a sequence of quick cluster leadership changes, requiring a node restart to recover.

Clustering

• #16534 Lowered the default net_ticktime from 2 minutes to 1 minute to improve cluster node failure detection.

In the event of a network outage or abrupt node termination, remaining nodes will detect the down node sooner, reducing the time before failover mechanisms activate and improving overall cluster resilience and user experience.

Plugins

• #16842 Reduced noisy plugin config warning logs when no peer node has the plugin config yet.

Previously, when a node tried to fetch plugin config from peer nodes during startup, it would log a warning even when all peers simply didn't have the config (e.g., first node to load the plugin). Now this benign case is logged at debug level, and only genuine errors (RPC failures, timeouts) remain as warnings.

• #16843 Fixed an issue where HTTP headers and query string parameters were not passed through to plugin API handlers, causing plugins to receive empty headers and missing query parameters.

• #16904 Prevent enabling or starting multiple versions of the same plugin at once. When a newer version is enabled, older configured versions of that plugin are automatically disabled, and management API actions now return a clear error instead of reporting success while another version is still active.

Gateway

• #16536 Fixed the CoAP Gateway when running in DTLS connection mode.

• #16996 Fixed CoAP DTLS connection-mode to keep sessions available after sock_closed and support reconnect takeover with the same clientid and valid token.

Observability

• #16879 Added log.audit.cache_size as the primary config key for the audit log DB cache size, while keeping log.audit.max_filter_size for backward compatibility.

Deployment and Security

• #16683 Added support for HTTPS CRL Distribution Point URLs in the CRL cache, so CRLs fetched from https:// endpoints are now cached and refreshed correctly.

• #16901 Fixed RPM package OpenSSL dependency for RHEL 9.6 LTS: pinned openssl >= 3.5.1 for RHEL >= 9.7 and openssl >= 3.0.7 for older RHEL 9 versions.

ExHook

• #16890 Fixed an ExHook issue where successful reconnect reloads could duplicate the same server name in the running list and trigger repeated callback dispatches.

Licensing

• #16764 Refined license customer tier handling by introducing STANDARD and VIP tiers in enforcement logic and reducing the official-license STANDARD expiry grace period from 90 days to 15 days before new sessions are restricted.