Bridge Extension - Troubleshooting Guide

Overview

This article addresses scenarios where the HiveMQ Enterprise Bridge Extension experiences unexpected queueing, or connection failures requiring the bridge to rejoin the remote broker.

Initial Analysis

Based on HiveMQ Enterprise Bridge Extension behavior, issues typically stem from one of the following :

Network connectivity problems between the bridge broker and remote broker
Configuration errors in the bridge extension setup
Remote broker availability or authentication failures
TLS/certificate validation issues when encryption is enabled

Identifying the Issue

Check HiveMQ Logs

The bridge extension logs errors in the HiveMQ log file.

Look for entries indicating:

Connection failures to the remote broker
Authentication errors
TLS handshake failures
Configuration validation errors

Verify Bridge Configuration

Ensure the bridge configuration file is properly set up at:

HIVEMQ_HOME/extensions/hivemq-bridge-extension/conf/config.xml

Review Connection Behavior

During startup or runtime connection problems, the bridge extension attempts to reconnect internally an unlimited number of times. The period between connection retries starts at one second and increases exponentially to a maximum of two minutes between attempts.

Resolution Steps

Step 1: Validate Configuration

Verify the minimum required configuration elements are present, as documented here : (https://docs.hivemq.com/hivemq-bridge-extension/latest/index.html)

A unique bridge name within your local node structure
Connection information for the remote broker
At least one topic filter to forward messages

Example minimum configuration:

<hivemq-bridge-extension>
    <bridges>
        <bridge>
            <name>your-unique-bridge-name</name>
            <remote-broker>
                <connection>
                    <static>
                        <host>the.hostname.of.remote.broker</host>
                    </static>
                </connection>
            </remote-broker>
            <topics>
                <topic>
                    <filter>a/topic/filter</filter>
                </topic>
            </topics>
        </bridge>
    </bridges>
</hivemq-bridge-extension>

Step 2: Check Remote Broker Connectivity

Verify network connectivity to the remote broker:

Confirm the remote broker hostname is resolvable
Verify the remote broker port is accessible
Check firewall rules between bridge and remote broker

Step 3: Verify Authentication Credentials

If authentication is configured, ensure credentials are correct :


<authentication>
    <mqtt-simple-authentication>
        <username>a-username</username>
        <password>a-user-password</password>
    </mqtt-simple-authentication>
</authentication>

Step 4: Hot Reload Configuration

If changes to the configuration are required, you can change the configuration of your HiveMQ Enterprise Bridge Extension during runtime :

Add a DISABLED file to the hivemq-bridge-extension folder
Change the configuration in the conf/config.xml file
Remove the DISABLED file from the hivemq-bridge-extension folder

Step 5: Monitor Reconnection Attempts

If a connection problem occurs during the extension startup or during runtime, the bridge extension attempts to reconnect internally an unlimited number of times. Monitor the logs to track reconnection progress.

Additional Resources

HiveMQ Enterprise Bridge Extension Documentation
HiveMQ Support Portal: https://hivemq.atlassian.net/servicedesk/customer/portal/1
HiveMQ Community Forum: https://community.hivemq.com/

Related Information

Configuration file location changed in HiveMQ 4.15.0 from bridge-configuration.xml to conf/config.xml.
If bridging from an entire HiveMQ cluster, install identically configured Enterprise Bridge Extensions on every broker node.

—

Last Updated: December 2025
Applies To: HiveMQ Enterprise Bridge Extension
```

Bridge Extension - Initial Troubleshooting