HiveMQ 4.28 (LTS) to 4.55 (LTS) Migration Guide

HiveMQ 4.55 is the new Long-Term Support (LTS) version of the HiveMQ MQTT Enterprise Broker.
HiveMQ 4.55 LTS is a drop-in replacement for HiveMQ 4.28.x LTS.

You can learn more about all the new features HiveMQ 4.55 introduces in our release blog post.

The HiveMQ software bundle includes the following components:

  • All HiveMQ Enterprise Extensions (disabled by default).

  • HiveMQ Data Hub.

  • The open-source MQTT CLI tool, in the tools folder of your HiveMQ installation.

  • The HiveMQ Swarm load-testing tool, in the tools folder of your HiveMQ installation.

Support Timeline

HiveMQ supports the previous 4.28.x LTS release for six months after the release of HiveMQ 4.55 LTS (through February 2027).
HiveMQ provides enhanced version compatibility for all releases.

For more information, see HiveMQ Rolling Upgrade Policy and our Introducing Flexible MQTT Platform Upgrades with HiveMQ blog post.

When you migrate from one HiveMQ version to another, we recommend that you review the upgrade information for each version between your current HiveMQ version and the target HiveMQ version.
To help ensure a smooth transition from one LTS version to the next, we compiled a list that highlights key changes from HiveMQ 4.28 to HiveMQ 4.55.

Known Issues

HiveMQ 4.55 LTS has no known issues.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported and it is possible to run HiveMQ version 4.28.x and version 4.55 simultaneously in the same cluster. By default, the HiveMQ cluster enables all new cluster features when all nodes are upgraded to the new version. No manual intervention is required.

Please follow the instructions in our user guide to ensure a seamless and successful rolling upgrade.

For more information, see HiveMQ Clustering Documentation.

Upgrade a Single-node HiveMQ Instance

  • Create a backup of the entire HiveMQ 4.28.x installation folder from which you want to migrate

  • Install HiveMQ 4.55 as described in the HiveMQ Installation Guide

  • Migrate the content of the config.xml and license files from your old HiveMQ 4.28.x installation.

  • To migrate your persistent data, copy everything from the data folder of your backup to the data folder of the new HiveMQ 4.55 installation. The first time you start HiveMQ, the file storage formats of the persistent data from your previous installation are automatically updated in the new persistent storage.

HiveMQ Configuration File Changes

The upgrade from HiveMQ 4.28.x to HiveMQ 4.55 does not require changes to your HiveMQ config.xml file.

HiveMQ prevents startup if your configuration file contains invalid values. For more information, see Configuration Validation.

HiveMQ Persistent Data Migration

When you migrate, HiveMQ 4.55 automatically updates the file storage formats of all the data that you copied into your new data folder.

To migrate the persistent data, you must copy everything in the data folder of the previous HiveMQ 4.28.x installation to the data folder of your new HiveMQ 4.55 installation.

Linux example
cp -r /opt/hivemq-4.28.0/data/* /opt/hivemq-4.55.0/data/

The first time you start HiveMQ 4.55, the file storage formats of the persistent data from your previous installation are automatically updated in the new persistent storage.

Key Changes from HiveMQ 4.28 (LTS) to HiveMQ 4.55 (LTS)

The following sections highlight upgrade-relevant changes between HiveMQ 4.28 and 4.55.

Table 1. Summary
Change Action required

New glibc requirement on Linux

Yes, if your system runs glibc versions earlier than 2.17, or earlier than 2.29 when using Data Hub transformations.

New HiveMQ Control Center

Yes, update bookmarks and links.

Enterprise Security Extension password handling

Yes, if you need the previous behavior.

ESE Helper tool changes

Yes, if scripts reference the tool.

Removed overload protection metrics

Yes, if dashboards use these metrics.

Custom extension class access

Yes, if you use custom extensions.

New minimum Kafka broker version

Yes, if you use a Kafka broker version older than 2.1.

Kafka extension configuration validation

Yes, if you use the Kafka extension.

Legacy Kafka Topic Mapping Tag

Yes, if you use the legacy <topic-mapping> tag in your Kafka extension.

Removed Jaeger propagator and Zipkin exporter

Yes, if you use the Distributed Tracing Extension

Usage statistics

No.

Docker images on Ubuntu 24.04 LTS

Yes, if you build custom images.

Docker images on Java 25

Yes, if you use legacy TLS MQTT clients.

Java TLS_RSA deprecation

Yes, if you use legacy TLS MQTT clients.

Removed Control Center v1 SDK methods

Yes, if custom extensions use these methods.

Jakarta EE 10 migration

Yes, if custom extensions register a RestApplication.

Bridge hostname verification

Yes, if you use TLS bridge connections.

New glibc Requirement on Linux-based Operating Systems

HiveMQ 4.55 requires the following minimum versions of the GNU C Library (glibc):

  • General HiveMQ broker and Data Hub operation: glibc 2.17 or higher.

  • HiveMQ Data Hub transformations: glibc 2.29 or higher.

Additionally, the system user running the HiveMQ processes must have write permissions for the /tmp system directory.

To check the glibc version on your system, run the ldd --version command on your machine. Or, check the distribution details for your operating system on distrowatch. For example, RedHat, Ubuntu, and OpenSUSE.

HiveMQ Data Hub Scripting and glibc

Data Hub transformation scripting requires glibc 2.29 or higher. Scripting is enabled by default. If your system does not meet the version requirement, HiveMQ cannot start.

To resolve this issue, do one of the following:

  1. Upgrade your system to meet the minimum glibc requirement.

  2. Disable the scripting feature in your config.xml file:

<data-hub>
    <scripting>
        <enabled>false</enabled>
    </scripting>
</data-hub>

New HiveMQ Control Center

Starting with HiveMQ 4.55 LTS, Control Center v1 is no longer available.
The new version of the Control Center is located at http://<host>:8080/v2/.
Update any bookmarks, links, or automations that reference the previous URL.

Since the migration removes CCv1, log out of CCv1 before you upgrade to HiveMQ 4.55 to prevent unnecessary error log messages.

For more information, see HiveMQ Control Center.

HiveMQ Enterprise Security Extension: Client Password Handling

The HiveMQ Enterprise Security Extension now clears the client password after the connection is established.

The clear-client-password-on-connection attribute controls this behavior:

  • true (default): The extension clears the client password.

  • false: The extension retains the client password, which matches the previous behavior.

To restore the previous behavior, set the attribute to false:

<enterprise-security-extension>
    <pipelines>
        <listener-pipeline listener="listener-other" clear-client-password-on-connection="false"/>
    </pipelines>
</enterprise-security-extension>

ESE Helper Tool Changes

The location and bundled-content of the ESE Helper command-line tool for the HiveMQ Enterprise Security Extension changed.

The ESE Helper now resides in the helper folder of the extension directory:

hivemq-enterprise-security-extension$ tree -L 1
.
├── README.html
├── README.txt
├── drivers
├── lib
├── conf
├── hivemq-enterprise-security-extension-1.0.0.jar
├── helper
│   ├── hivemq-ese-helper
│   └── hivemq-ese-helper.jar
├── hivemq-extension.xml
├── third-party-licenses
└── scripts

The helper folder contains the following files:

  • hivemq-ese-helper: The Bash wrapper script.

  • hivemq-ese-helper.jar: The JAR file, which requires Java 21 or higher.

The following binaries are no longer included in the helper folder:

  • The binary executable for Darwin (macOS).

  • The binary executable for GNU/Linux.

If you reference the previous path in any scripts or automated workflows, you must update paths accordingly to ensure continued compatibility.

For complete configuration details, see ESE Helper Tool.

Removed Client Overload Protection Metrics

HiveMQ 4.35 introduced improved client overload protection.

Starting with HiveMQ 4.35, the following obsolete client overload protection metrics are no longer reported:

  • com.hivemq.overload-protection.credits.per-tick

  • com.hivemq.overload-protection.clients.average-credits

  • com.hivemq.overload-protection.credits.subtracted.publishes

  • com.hivemq.overload-protection.credits.subtracted.subscribes

  • com.hivemq.overload-protection.credits.subtracted.unsubscribes

Update any dashboards or alerts that use these metrics.

Changes to Custom Extension Class Access

HiveMQ 4.55 LTS includes enhanced security for extension class loading.

If you plan to upgrade to HiveMQ 4.55 from a version earlier than HiveMQ 4.44 and you use custom extensions, prepare your extensions before the upgrade.

Before HiveMQ 4.44, custom extensions had direct access to HiveMQ broker classes. Starting with HiveMQ 4.44, extensions no longer have direct access to broker classes. The change aligns with industry best practices for secure extension development and ensures clear application isolation.

If you upgrade from a version earlier than HiveMQ 4.44 and you use custom extensions, test your custom extensions against HiveMQ 4.55 in a staging environment. If an extension does not start, the HiveMQ logs typically display a java.lang.ClassNotFoundException error that indicates a missing class. To resolve class loading issues, include the required classes in your extension packages.

New Minimum Kafka Broker Version for the HiveMQ Enterprise Extension for Kafka

The minimum Kafka broker version changes from 0.10.2 to 2.1.

Before you upgrade to HiveMQ 4.55 LTS, confirm that your Kafka brokers run version 2.1 or higher.

Default Configuration Validation in the HiveMQ Enterprise Extension for Kafka

Starting with HiveMQ 4.55, HiveMQ validates your extension configuration file against a schema to prevent misconfiguration or unexpected behavior.
When an invalid extension config.xml file is detected, the extension does not start.

Validate your Kafka extension config.xml file before you upgrade to HiveMQ 4.55.

End of Backward Compatibility for Legacy Kafka Topic Mapping Tag

HiveMQ 4.55 ends support for the legacy <topic-mapping> tag in the HiveMQ Enterprise Extension for Kafka.

The <mqtt-to-kafka-mappings> and <mqtt-to-kafka-mapping> tags replaced this tag in version 1.1.0 of the HiveMQ Enterprise Extension for Kafka.

Update any Kafka mappings that still use the legacy <topic-mapping> tag before you update to HiveMQ 4.55.

Removed Deprecated Jaeger Propagator and Zipkin Exporter from Distributed Tracing Extension

The HiveMQ Distributed Tracing Extension no longer supports the Jaeger trace propagator and the Zipkin span exporter. Both are deprecated in the OpenTelemetry specification.

If your config.xml of the HiveMQ Distributed Tracing Extension uses any of the following, you must update it before upgrading:

  • jaeger in the <propagators> configuration.
    Replace it with tracecontext (W3C Trace Context).

  • <zipkin-exporter> in the <exporters> configuration.
    Replace it with an <otlp-exporter> that points to an OTLP-compatible endpoint.

For more information, see HiveMQ Distributed Tracing Extension.

HiveMQ Usage Statistics

Starting with HiveMQ 4.47, anonymous usage tracking is enabled by default. This data helps us understand how the product is used and guides future improvements.

HiveMQ 4.50 adds an enhanced usage statistics function that sends data periodically to https://analytics.hivemq.com/v2. The new statistics function operates alongside the existing anonymous usage statistics function and collects the same data as well as additional information to help us better understand how HiveMQ is deployed and used.

The additional data includes a cluster identifier, basic license information, message usage metrics, and extension IDs. This data supports platform improvements, compatibility planning, and extension ecosystem development. For a complete list of the data collected, see Usage Statistics.

HiveMQ Platform Docker Images Upgraded to Ubuntu 24.04 LTS

The HiveMQ Platform Docker images now run on Ubuntu 24.04 LTS (Noble Numbat). The upgrade from Ubuntu 22.04 LTS to Ubuntu 24.04 LTS provides the latest security enhancements, refreshed system libraries, and an extended support window.

If you build custom Docker images on top of the HiveMQ base image, test your images against the new base before you deploy to production.

This change affects deployments that use HiveMQ Platform Docker images only. Bare-metal and VM-based deployments are not affected.

HiveMQ Platform Docker Images Update to Java 25

The HiveMQ Platform Docker images now ship with Java 25. This version deprecates outdated TLS_RSA cipher suites and SHA-1 signatures.

For more information, see Critical Java Security Update.

Critical Java Security Update

TLS_RSA deprecation in JDK-21.0.10 and JDK-25 can cause MQTT connection failures.

Oracle introduced the following security updates in JDK-21.0.10 and JDK-25:

  • TLS_RSA cipher suites are disabled by default The JVM now rejects these cipher suites during TLS handshakes due to a lack of forward secrecy.

  • SHA-1 signatures disabled for TLS 1.2 / DTLS 1.2 The JVM no longer accepts SHA-1 signatures during handshakes because the algorithm is no longer considered cryptographically secure.

These updates improve platform security. However, they remove compatibility with legacy MQTT clients that depend on RSA key-exchange ciphers.

These changes are introduced by the Java platform vendor Oracle, not by HiveMQ.
The changes directly affect how MQTT clients connect to any HiveMQ deployment that runs on the updated JDK.

If you plan to upgrade to JDK 21.0.10 (released January 20, 2026) or JDK 25 (released September 16, 2025), read this article to understand the impact and prepare your HiveMQ deployment.

Breaking Changes

HiveMQ 4.55 LTS introduces breaking changes in the HiveMQ Enterprise Extension SDK and the HiveMQ Enterprise Bridge Extension configuration.

Starting in HiveMQ 4.53, the affected APIs were deprecated and logged warnings to help you prepare.

Control Center v1 Removal (Enterprise Extension SDK)

As part of the Control Center v1 retirement, HiveMQ 4.55 LTS removes the following methods:

  • ControlCenterService.addView()

  • ControlCenterService.addViews()

  • LoginLoadOutput.showLoginComponents()

Remove these method calls from your extensions before you upgrade to HiveMQ 4.55 LTS.

Jakarta EE 10 Migration (Enterprise Extension SDK)

Extensions that register a RestApplication through RestServicePerExtension.setRestApplication() currently use javax.ws.rs (JAX-RS 2.x).

HiveMQ 4.55 LTS migrates HiveMQ to Jakarta EE 10. This change moves the package namespace from javax.ws.rs (JAX-RS 2.x) to jakarta.ws.rs, which introduces a breaking change in these method calls.

Starting in HiveMQ 4.53, RestServicePerExtension.setRestApplication() logs a deprecation warning when the broker detects a javax.ws.rs (JAX-RS) application. To prepare, migrate your annotations and exception types to the jakarta.* namespace before you upgrade to HiveMQ 4.55 LTS.

Default Netty 4.2 Hostname Verification in the HiveMQ Enterprise Bridge Extension

HiveMQ 4.55 LTS upgrades to Netty 4.2, which enforces hostname verification for all outbound TLS connections.

The remote broker certificate must list the configured hostname in its common name (CN) or subject alternative names (SANs). Otherwise, the bridge fails to connect.

Verify that each remote broker certificate includes the configured hostname before you upgrade to HiveMQ 4.55.

Get Help

For further assistance, contact HiveMQ support.