Skip to main content

Troubleshoot the MQTT Integration

availability
Feature availability by platform, plan type, and user type
Platform:AvailableWebNot availableMobile
Plan Type:Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:Not availableRequesterNot availableFull UserAvailableAdministrator

If the MQTT integration or the MaintainX® MQTT On-Premise Agent (referred to as the OPA) isn't behaving as expected, use the sections below to identify and resolve common issues.

Not Seeing Data in MaintainX​

If tags aren't being created or their values aren't updating in MaintainX, work through the following checks:

Agent Is Unable to Connect to the MQTT Broker​

If you use the hostname or fully qualified domain name (FQDN) for your MQTT broker, a Domain Name System (DNS) issue might prevent the OPA from connecting. This issue is most commonly observed in Windows environments. To resolve it, add your DNS server to the Docker container.

To add your DNS server to the Docker container:

  1. Stop and remove the current container, then start it again with the --dns flag:

    docker stop on-premise-agent
    docker rm on-premise-agent
    docker run --dns={YourDnsIp} -d --name on-premise-agent -v $HOME/.maintainx/sensor-connect:/config -v $HOME/.maintainx/opa-certificates:/run/secrets maintainx/on-premise-agent:latest
    tip

    You can add --dns={YourDnsIp} for each DNS server you want to add.

  2. Verify that the OPA is running and connected to your MQTT broker.

    docker logs -f on-premise-agent

Agent Fails to Start With a Validation Error​

The OPA validates MqttSubscriptionSettings at startup. If validation fails, the error message in the OPA's logs identifies the offending subscription by its index in the Subscriptions array.

The two most common validation failures are:

  • # wildcard in a Custom subscription: Custom subscriptions don't support the # wildcard. Replace # with a + for each level. For more information, see Wildcard Rules.
  • FriendlyName on a Raw subscription whose topic ends with +: Raw subscriptions with wildcard topics can't have a FriendlyName. Remove the FriendlyName. For more information, see Wildcard Rules.

Tags Aren't Being Created​

Tail the OPA logs to find out why:

docker logs -f on-premise-agent

Look for the following log messages, which indicate common causes:

  • Topic did not match any subscription: The broker is delivering messages, but no topic pattern matches them. Check for typos, and remember that Custom subscriptions don't support #.
  • No sensor values parsed for topic: ...: The topic matched, but the OPA couldn't decode the payload. For Json subscriptions, this usually means the JSON is malformed or the configured path doesn't exist in the payload.
  • Skipping JSON payload for Raw+Auto topic ... (debug level): A Raw + Auto subscription received a JSON-shaped payload and skipped it. Switch the subscription to Json encoding.

Tag Values Stop Updating After a Configuration Change​

Look for the type-mismatch warning quoted in Data Type Locking. If you see it, the tag's type was locked when the OPA created it, and the OPA is dropping the new payloads. Delete the tag in MaintainX, and the OPA recreates it on the next payload.

Tags Receive Values From the Wrong Subscription​

Check the OPA logs for a warning about overlapping or duplicate subscriptions. If two or more topic patterns in Subscriptions can match the same incoming topic, the OPA applies only the first matching subscription and ignores the others. To fix this, make each topic pattern distinct. For more information, see Overlapping Subscriptions.

Contact MaintainX Support​

If your issue isn't listed here or you continue to experience problems, contact MaintainX Support. Include the OPA logs to help us investigate.