Documentationbreadcrumb arrow Pluginsbreadcrumb arrow MQTTbreadcrumb arrow Troubleshooting
Grafana Cloud Enterprise Open source
Last reviewed: February 20, 2026

Troubleshoot MQTT data source issues

This document provides solutions to common issues you may encounter when configuring or using the MQTT data source. For configuration instructions, refer to Configure the MQTT data source.

Connection errors

These errors occur when Grafana can’t connect to the MQTT broker.

“MQTT Disconnected” on Save & test

Symptoms:

  • Clicking Save & test displays MQTT Disconnected.
  • Panels show no data.

Possible causes and solutions:

CauseSolution
Incorrect URIVerify the URI includes the correct scheme (tcp://, tls://, ws://, or wss://), host, and port. For example, tcp://localhost:1883. The aliases mqtt://, ssl://, tcps://, and mqtts:// are also accepted.
Broker not runningConfirm the MQTT broker is running and accepting connections on the specified port.
Firewall or network restrictionsEnsure the Grafana server can reach the broker’s host and port. Check firewall rules and security groups.
Wrong scheme for TLSIf the broker requires TLS, use tls:// instead of tcp://.
DNS resolution failureVerify the broker hostname resolves correctly from the Grafana server.

Connection drops or intermittent disconnections

Symptoms:

  • Panels stop updating and then resume after a delay.
  • Grafana logs show “MQTT Connection lost” warnings.

Solutions:

  1. Check the MQTT broker logs for client evictions or connection limits.
  2. Ensure only one Grafana instance uses each Client ID. If multiple instances share a Client ID, the broker disconnects the older connection.
  3. Verify network stability between the Grafana server and the broker.
  4. The plugin automatically reconnects after a disconnection with a maximum interval of 10 seconds.

Authentication errors

These errors occur when credentials or TLS certificates are invalid.

“error connecting to MQTT broker” with credentials

Symptoms:

  • Save & test fails with an error mentioning connection failure.
  • Broker logs show authentication rejections.

Possible causes and solutions:

CauseSolution
Wrong username or passwordRe-enter the credentials in the data source configuration. Passwords are stored securely and can’t be viewed after saving. Click the reset button and enter the password again.
Missing credentialsSome brokers reject anonymous connections. Add a Username and Password if required.
Account disabled or expiredVerify the account is active in your MQTT broker’s user management system.

TLS certificate errors

Symptoms:

  • Connection fails when using tls:// scheme.
  • Error messages mention certificate verification, handshake failure, or key mismatch.

Possible causes and solutions:

CauseSolution
Self-signed server certificateEnable With CA Cert and paste your CA certificate, or enable Skip TLS Verification for testing.
Expired certificateCheck expiration dates on your CA, client, and server certificates. Renew any expired certificates.
Mismatched client cert and keyEnsure the Client Cert and Client Key are a matching pair. Regenerate them if necessary.
Wrong CA certificateVerify the CA Cert is the certificate that signed the broker’s server certificate.
Certificate formatEnsure certificates are PEM-encoded (starting with -----BEGIN CERTIFICATE-----).

Caution

Enabling Skip TLS Verification disables certificate chain and hostname verification. Use this only for testing, not in production environments.

Query errors

These errors occur when subscribing to topics or processing messages.

No data in panels

Symptoms:

  • The panel shows “No data” despite the data source being connected.
  • The connection test shows MQTT Connected but panels are empty.

Possible causes and solutions:

CauseSolution
Empty topicEnsure the Topic field in the query editor isn’t blank.
No messages on topicVerify that messages are being published to the topic using an MQTT client tool such as mosquitto_sub.
Wrong topic pathDouble-check the topic path for typos. MQTT topics are case-sensitive.
Panel time rangeThe time range selector doesn’t affect MQTT streaming. Data only appears while the panel is open and receiving messages.
Retained messages onlyIf the topic only has a retained message, it appears once on subscription. New data requires new messages to be published.

Unexpected field types or missing fields

Symptoms:

  • Numeric values appear as strings.
  • JSON object keys are missing from the data frame.

Solutions:

  1. Ensure numeric values are published without quotes (for example, 23.5 not "23.5").
  2. For JSON payloads, only top-level keys are extracted into separate fields. Nested objects appear as JSON-typed fields. Use the Extract fields transformation to access nested values.
  3. If the first message defines a field as one type and a later message sends a different type for the same key, the later value is dropped. Ensure consistent data types across messages.

Performance issues

These issues relate to high message volumes or resource usage.

High CPU or memory usage

Symptoms:

  • Grafana uses excessive resources when many MQTT topics are active.
  • Dashboard panels lag or become unresponsive.

Solutions:

  1. Reduce the number of subscribed topics per dashboard.
  2. Increase the query interval to reduce the frequency of data frame generation. A longer interval buffers more messages per push but reduces processing overhead.
  3. Avoid subscribing to broad wildcard topics (such as #) that match large numbers of subtopics.
  4. Close dashboards and panels you aren’t actively using, since each open panel maintains an active subscription.

Enable debug logging

To capture detailed error information for troubleshooting:

  1. Set the Grafana log level to debug in the configuration file:

    ini 
    [log]
level = debug

  2. Restart Grafana for the change to take effect.

  3. Review logs in /var/log/grafana/grafana.log (or your configured log location).

  4. Look for entries with “MQTT” that include connection, subscription, and message details.

  5. Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you’ve tried the solutions in this document and still encounter issues:

  1. Check the Grafana community forums for similar issues and discussions.
  2. Review the MQTT datasource GitHub issues for known bugs and feature requests.
  3. Consult the MQTT v3.1.1 specification for protocol-level guidance.
  4. Contact Grafana Support if you’re a Cloud Pro, Cloud Advanced, or Enterprise customer.
  5. When reporting issues, include:
    • Grafana version and plugin version
    • Error messages (redact credentials and sensitive information)
    • Steps to reproduce the issue
    • Relevant broker configuration (redact credentials)