HiveMQ 4.54.x to 4.55.x Migration Guide

This is a minor HiveMQ upgrade. HiveMQ 4.55 is a drop-in replacement for HiveMQ 4.54.x.

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

The HiveMQ software bundle is prepackaged with all HiveMQ Enterprise Extensions (disabled), HiveMQ Data Hub, the open-source MQTT CLI tool, and the HiveMQ Swarm load-testing tool. MQTT CLI and HiveMQ Swarm are located in the tools folder of your HiveMQ installation.

HiveMQ 4.55 is the new HiveMQ LTS (Long Term Support) release. The previous 4.28.x LTS release is supported through February 2027. For more information, see the HiveMQ 4.28 to 4.55 Migration Guide, HiveMQ Rolling Upgrade Policy, and our Managing HiveMQ Releases and Support 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.
Note changes that are relevant to your use case and adjust your configuration as needed.

Changes to Review Before You Upgrade to HiveMQ 4.55 LTS Release from HiveMQ 4.54

HiveMQ 4.55 LTS introduces breaking changes in the HiveMQ Enterprise Extension SDK. Review your custom extensions before you upgrade. Security improvements also change how you configure the HiveMQ Enterprise Bridge Extension.

Control Center v1 Removal (Enterprise Extension SDK)

HiveMQ 4.55 removes ControlCenterService.addView(), ControlCenterService.addViews(), and LoginLoadOutput.showLoginComponents() as part of the Control Center v1 retirement.

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

Jakarta EE 10 Migration (Enterprise Extension SDK)

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

HiveMQ 4.55 migrates to Jakarta EE 10. This change moves the package namespace to jakarta.ws.rs, which introduces a breaking change for these method calls.

Migrate your custom extension annotations and exception types to the jakarta.* namespace before you upgrade to HiveMQ 4.55.

Default Netty 4.2 Hostname Verification in the HiveMQ Enterprise Bridge Extension

The HiveMQ 4.55 release upgrades HiveMQ to Netty 4.2. Netty 4.2 enforces hostname verification for all outbound TLS connections. Bridges whose remote broker certificate does not list the configured hostname in its CN or SANs will fail to connect.

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

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.

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.

Known Issues

HiveMQ 4.55 has no known issues.

Upgrade a HiveMQ Cluster

Rolling upgrades are supported, and it is possible to run HiveMQ version 4.54 and version 4.55 simultaneously in the same cluster. By default, the HiveMQ cluster enables all new cluster features once 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.

Upgrade a Single-node HiveMQ Instance

  • Create a backup of the entire HiveMQ 4.54.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.54.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.

HiveMQ Configuration File Changes

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

HiveMQ Persistent Data Migration

When you migrate, HiveMQ 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.54.x installation to the data folder of your new HiveMQ 4.55 installation.

Linux example
cp -r /opt/hivemq-4.54.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.