Troubleshoot an MQTT status display

Open Settings, Integrations, and the display. Start with the Diagnostics checklist. Export the sanitized diagnostics when you need to send evidence to support.

The broker test fails

1. Confirm that the hostname resolves from the Print Hive service.
2. Confirm that port 8883 accepts MQTT over TLS.
3. Confirm that the TLS certificate matches the broker hostname.
4. Confirm that the Mosquitto Dynamic Security plugin is enabled.
5. Confirm that the management username can create clients and ACL roles.

Print Hive does not offer a switch to disable certificate or hostname checks. Replace an invalid certificate or add the correct private CA.

The pairing token fails

1. Generate a new token if the old token is more than ten minutes old.
2. Paste the pairing service URL into the Usermod. Do not open it as a browser page.
3. Confirm that the controller clock and network connection are valid.
4. Confirm that another controller did not already bind the token.

A retry from the same device nonce can return the same short-lived result. A different device nonce cannot claim the token.

The controller is online but pixels are unknown

Dim purple means that Print Hive cannot prove current source state. A fresh MQTT connection does not refresh stale Printer evidence.

1. Check that Hive Link reports current Printer telemetry.
2. Check that the Printer assignment still points to the current Host lease.
3. Select Request resync to request a complete current snapshot.
4. Wait for the next ten-second snapshot.

A published mapping does not appear

1. Confirm that the draft has one record for every physical pixel.
2. Confirm that duplicate Printer assignments are allowed or removed.
3. Confirm that the configured pixel count matches controller capabilities.
4. Check that Configuration applied is complete in Diagnostics.
5. Select Request resync.

The controller applies only a complete configuration with a valid hash. It keeps the prior complete configuration when a part is missing.

The strip order or colors are wrong

1. Run Walk pixels to check physical order.
2. Use Reverse order or swap individual assignments.
3. Run Test colors.
4. Correct the WLED strip type and color order on the controller.
5. Record a new physical strip confirmation.

A revoked credential still appears active

A credential stays in revoke_pending until Mosquitto confirms that it disabled the account and disconnected the session. Check the Dynamic Security control topic and the broker service logs.

Print Hive stops cloud publication while revocation is pending. Do not delete the record or issue an organization-wide MQTT credential.

The display returns after a broker move

Moving a display changes its binding epoch. Old retained messages and old credentials cannot authorize the new binding. Pair the controller again, then publish the current mapping.

Return to Set up an MQTT status display.