Migrate Data from HiveMQ 3 to HiveMQ 4

HiveMQ 4 introduces many new features and enhancements and is the first HiveMQ version that is
100% MQTT 5 compliant. HiveMQ 4 is a major version and is not compatible with earlier HiveMQ 3 versions.

Since HiveMQ 3.4.4, a data-export feature enables the seamless migration of persistent data between HiveMQ 3 and HiveMQ 4. To use this migration option, you need to migrate from HiveMQ version 3.4.4 to HiveMQ version 4.2.1 or higher.


  • Your HiveMQ 3 cluster runs HiveMQ 3.4.4. If you have not already done so, upgrade your 3.x.x version of HiveMQ to HiveMQ 3.4.4. You can download HiveMQ 3.4.4 here. The upgrade from a 3.4.x version to 3.4.4 is a drop-in replacement and does not require any downtime. For upgrade instructions, see Rolling Upgrades.

  • Your target cluster runs HiveMQ 4.2.1 (or higher). On a fresh cluster, install HiveMQ 4.2.1 or higher as described in the HiveMQ Installation Guide.

Export Data From HiveMQ 3

  • Go to the Web UI of your HiveMQ 3.4.4 installation and select Migration.

    • To start the export process, click Export Now.

Migration page

You can only generate this export one time. If you need to redo the export, you must manually delete the previously-generated export file from the HIVEMQ_HOME/backup folder on the cluster node where the backup was created.
  • To confirm your export request, click Export Now.

Export Now

  • To complete the export process, click OK.

Export Finished

If a node joins or leaves the cluster during the export process or the cluster is fragmented due to network issues, HiveMQ cancels the export automatically. The Export Finished dialog indicates that the export was not successful. After you resolve the problem, you must restart the export.
  • To start the download of the finished export, click Download Export.

Download Export

  • When preparation of the download file is complete, click Save.

    • When prompted, specify a location to store the export on your file system and click Save File.

Import Data to HiveMQ 4

  • Go to the control center of your freshly-installed HiveMQ 4.2.1 (or higher) cluster and select Backup.

    • To open a dialog where you can select the 3.4.4 migration file that you exported, click the Restore from Backup input field.

    • Select the 3.4.4 migration file that you exported and click Open.

    • To import the selected migration file to your cluster, click Upload.

Import to HiveMQ 4

Since HiveMQ 4, the Web UI is named Control Center.
  • Review the information in the confirmation dialog. To start the import, click Restore.

Confirm Import

While the import is processed, you can leave the Backup page.
  • When the import is finished, an alert dialog notifies you that the import finished successfully. To close the alert dialog and complete your migration from HiveMQ 3 to HiveMQ 4, click OK.

Complete Migration

For detailed information on the improvements and new features that HiveMQ 4 introduces, see HiveMQ 4.2, 4.1, and 4.

For detailed information on the configuration changes HiveMQ 4 introduces, see the Configuration File Upgrade section of the 3.x.x to 4.0.x Migration Guide.