The MQTT broker shows incoming messages. Your publisher is online, and a dashboard may even display the latest value. But the historian has no new records. Where should you look first?
Start by separating five questions: Did the broker accept the message? Did the historian’s subscriber receive it? Did the ingestion process understand it? Did the database accept the write? Can you retrieve the resulting record? A successful connection answers only part of that chain.
First, capture one message you can trace
Choose a single equipment tag and publish a controlled test message through the approved production path. For example, a pump gateway might publish to plant/line2/pump07/pressure:
{
"device_id": "P-07",
"ts": "2026-10-27T08:14:23Z",
"pressure_kpa": 642.5
}
This is an illustrative payload, not a TDengine connector configuration. Record the exact topic, payload bytes, broker timestamp, publisher identity, expected destination table, and intended source timestamp. If the application supports a message or sequence identifier, capture it too.
Use a fresh test timestamp and avoid repeatedly sending an identical record while trying to diagnose missing data. Depending on the table design and write rules, identical timestamps can make a successful test hard to distinguish from an earlier write.
1. Prove broker receipt, not just publisher connectivity
A connected publisher can still use the wrong topic, publish to another broker endpoint, or receive a failed authorization result. Compare the publish event with broker-side evidence for the same topic and test interval.
Check the hostname, port, TLS listener, and environment. Development and production brokers are easy to confuse when they share similar topic names. Then inspect the broker’s accepted-message metrics or logs, where available. A publisher-side acknowledgement establishes MQTT delivery on that hop; it does not establish delivery to the historian.
If the broker has no evidence of your test message, stop here. Debugging table mapping will not help until the correct broker receives the intended publication.
2. Verify the subscriber and topic filter
Next, confirm that the ingestion client is connected to the same broker and has a successful subscription for the topic you tested. Do not treat a general connection-health check as proof of an active, matching subscription.
Work through these checks:
- Topic filter: MQTT topic matching is case-sensitive.
plant/+/pump07/pressurematches one intermediate topic level;plant/#can match multiple remaining levels. A near match is still a miss. - Subscription result: Check the SUBACK result or the connector’s subscription logs, where exposed. Connection success alone does not mean the broker accepted the requested filter or QoS.
- Identity and permissions: Confirm the subscriber’s account can subscribe to the intended topic. Publishing permission does not necessarily imply subscription permission.
- Client ID: Ensure another connection is not using the same client identifier and displacing this collector. Stable IDs matter for session recovery, but IDs must remain unique among simultaneous clients.
- Shared subscriptions: If the client uses a
$share/...filter, messages may be distributed across group members. One individual collector will not necessarily see every publication.
A temporary independent subscriber using equivalent broker credentials and an appropriate topic filter can help locate the break. Use it only where operational policy permits, and avoid changing production subscription groups just to run the test.
3. Check what the ingestion process actually parses
Receiving the MQTT PUBLISH packet is not the same as extracting valid historical data. Plain MQTT does not prescribe a JSON schema, equipment identifier, or source-timestamp field.
Inspect the collector’s raw-message view or parsing preview if available. Confirm that the actual payload is JSON when the task expects JSON, then check field names, capitalization, nested objects, number types, and missing values. A message containing pressure_kpa cannot populate a mapping that looks for pressure without an explicit transformation.
Treat topic parsing separately from payload parsing. The topic may supply site and equipment identity while the payload supplies the measurement and timestamp. Both sets of fields must reach the intended mapping. Also check the destination table name and any required tags; a valid numeric value is not enough if the equipment identity or destination is unresolved.
For the test message above, verify that ts is interpreted as the intended instant, not as an arbitrary local-time string. A rejected, null, or out-of-range primary timestamp can make the write fail even while message intake continues.
4. Follow the write path and its errors
Now inspect the ingestion task and database sink. Is the task processing source messages? Are accepted records moving toward the target? Are write errors or queue backlogs increasing?
A useful symptom map is:
| Observation | More likely next check |
|---|---|
| Broker receives messages; the ingestion subscriber receives none | Topic filter, access control, subscription result, client identity |
| Subscriber receives messages; parsed rows stay at zero | Payload format, field extraction, filtering rules |
| Parsed rows appear; database writes fail | Timestamp, schema, table name, permissions, target availability |
| Writes are reported; expected query shows nothing | Target database, table, query time range, timestamp interpretation |
For example, TDengine’s Enterprise MQTT ingestion connector is configured in taosExplorer and uses taosX to subscribe to broker topics, parse message or topic fields, and map results into TDengine tables. Its task status and health information help distinguish source problems from sink errors. A task marked Running does not, by itself, prove that the expected historical row was committed.
The connector also documents exception strategies such as archiving invalid records, discarding them, reporting errors, or caching in supported failure cases. Check the configured strategy before interpreting a quiet task as healthy. A discarded record may not produce a visible row, while a cached record may not yet be available to a query.
The appropriate destination for validated historical records is a time-series store such as TDengine TSDB; the MQTT broker alone is not that final destination. Connector features and availability depend on the product edition and deployment, so check the current MQTT ingestion documentation before relying on a specific control.
5. Query the right history, then compare the counts
After the ingestion task reports successful writes, query the actual target database and table. Use a time window that includes the source timestamp, not just the moment you published the message. During replay or retry, those two times may differ substantially.
Verify the selected subtable or equipment tag and inspect the exact measurement column. A record can exist in the wrong destination or under an unexpected timestamp while a dashboard querying a different slice remains blank.
For a controlled test, compare five pieces of evidence: one published message, one broker receipt, one subscriber receipt, one accepted write, and one queryable historical record. If any count diverges, focus on the boundary immediately before the divergence. Avoid concluding that QoS is the problem merely because the final row is missing.
Keep the diagnostic path reproducible
When the immediate issue is resolved, preserve the test topic, approved payload example, mapping version, task logs, and query that demonstrated success. Repeat the test after topic changes, credential rotation, schema updates, and connector upgrades.
For other industrial source protocols, the same principle applies: a working connection is not proof of complete history. Our OPC UA connected-but-no-historian-data troubleshooting guide uses a similar source-to-storage verification approach, with OPC UA-specific failure points.
The fastest MQTT investigation is not a search for one magic setting. It is a trace of one known message through each boundary until you can explain exactly where the expected historical record disappeared.
