Troubleshooting
Why OPC UA structs arrive at MQTT as type index 21
Short answer
The struct is not broken on the wire: it travels as an ExtensionObject, OPC UA built-in type 22, decodable only by a client that reads the server's type dictionary. A gateway that skips that lookup prints a placeholder, type index 21, instead of the members. Select the leaf member nodes and rebuild the struct in the consumer.
On this page
The members are not lost on the wire, and the server is not at fault. A structured OPC UA variable travels as an ExtensionObject — built-in type 22 — and a gateway that never reads the server's type dictionary cannot turn that binary body into name/value pairs, so its MQTT sink prints a placeholder such as <Type index: 21> and reports dataType: 22. The fix is client-side and proven: select each leaf member as its own read node and rebuild the structure in the consumer. The sections below pinpoint the failing hop, explain the two numbers, give the procedure and the verification, and state the one trade-off you accept.
What the two numbers in the message mean #
OPC UA builds everything — scalars, arrays, structures, messages — from one fixed table of built-in types. Entry 22 in that table is ExtensionObject, the envelope for every type the table does not name. When the payload reports dataType: 22, the gateway is telling you exactly what it holds: an ExtensionObject, not a decoded structure.
Part 6 of the OPC UA specification, the binary encoding mapping, defines the envelope. It is a run of bytes prefixed by the NodeId of the structure's data-type encoding, the encoding that was used, and the byte count. The bytes carry the structure's fields and nothing else; the field layout travels separately. A server publishes the layout as a type dictionary — an XML DataTypeDictionary exposed through a variable of type DataTypeDictionaryType — and the specification obliges the server to describe how each structured type is encoded and to hand that description to the client that needs it. That dictionary is the mechanism defined for custom types up to OPC UA version 1.04, and it is why the layout is never inside the message itself.
A client that performs the lookup expands the members. A client that skips it holds an opaque blob with no layout to serialize against, and prints <Type index: 21> for the value. When a client at least attempts the lookup and fails out loud, you see a different symptom first — resolving OPC UA DataType not found in dictionary warnings covers that variant.
Which hop drops the members #
The path under test is controller, OPC UA server, gateway read task, MQTT sink, broker, database consumer — the standard layout for bridging OPC UA PLC data to MQTT with an edge PC. Run the four checks in order; each one eliminates a hop.
| Check | What you do | What you see | What it proves |
|---|---|---|---|
| 1 | Browse the structure node in a desktop OPC UA client | DataType shows the structure name; the value lists every member, nested structures included | Server and type definition are fine; the fault is downstream. Go to 2 |
| 2 | Subscribe to the broker topic with a plain MQTT client | <Type index: 21> and dataType: 22 in the payload |
The placeholder is on the wire; broker, consumer and database are cleared. Go to 3 |
| 3 | Select one member of the same structure as its own node | The member's name and value in the message | Read task, sink, topic and credentials all work; only the structured type fails. Go to 4 |
| 4 | Compare the structure's DataType against the built-in type table | A custom structure type, not a scalar | The value passes the gateway as an opaque type — apply the leaf-node fix |
Whether the read task refuses to expand the structure or the sink refuses to serialize it makes no difference to the remedy, and check 3 already settles the split: the sink writes decoded scalar values correctly, so the chain that fails on the structure works on its members.
Select the leaf member nodes #
- Browse the structure in the desktop client and list every leaf member, including members inside nested structures.
- In the gateway's OPC UA read task, replace the structure node with those leaf nodes, keeping each leaf under its structure path so the message name still identifies the parent.
- Remove the parent structure node from the list; left in, it publishes the placeholder beside the valid member messages.
- Point the MQTT sink at one topic or one payload object shared by all members of the structure.
- Redeploy the configuration and restart the read task so it subscribes with the new node list.
For nested structures, take the leaves of the inner structure, never the inner structure node — it is an ExtensionObject in its own right and produces the same placeholder.
| Node you select | What arrives at MQTT |
|---|---|
| Top-level structure | <Type index: 21> with dataType: 22 |
| A structure nested inside it | The same placeholder |
| A leaf member | The member's name and value |
Rebuild the structure in the consumer #
Group the messages by the structure prefix in the variable name and write them as one row or record; the insert side is the pattern for logging PLC values from an OPC server into SQL Server, applied once each member arrives as its own message.
Members are read as separate items, so their source timestamps can straddle two controller cycles, and a row assembled from them can mix values from adjacent cycles. Hold the row together one of two ways:
- Store each message with its timestamp and assemble the row only from members inside one time window.
- Have the controller write a data-ready member that changes only after the whole structure is updated, and key the row insert on that member's arrival.
Worked example, illustrative numbers: one structure with 8 scalar members plus a nested structure of 3 gives 11 leaf nodes. On a 5 s cyclic publish that is 11 × 720 = 7,920 messages per hour per structure instance; twelve identical lines give 7,920 × 12 = 95,040 messages per hour, an average of 95,040 ÷ 3,600 = 26.4 messages per second. That rate is easy traffic for a plant broker, so the decision lands on the database: keep cyclic publishing only if the row volume suits it, otherwise move the members to publish-on-change with a deadband before touching the cycle time.
Verify the fix end to end #
- Subscribe to the broker with a wildcard on the connector's topic prefix.
- Confirm every selected leaf produces a message carrying its variable name and a value, and that no message contains
dataType: 22. - Write a distinct value to one member from the engineering tool, then read the same value in the desktop client and in the MQTT payload.
- Repeat with a member of the nested structure.
- After one full update cycle, confirm the database row carries every member.
What to recheck later, and one boundary #
Structure-level reads deserve one retest after every gateway update. Decoding structured types is a client capability that vendors do add, and checks 1 and 2 settle in ten minutes whether a structure node now serializes. Until one does, leaf selection is the correct configuration, not a stopgap.
Do not spend plant downtime on the server. When check 1 lists every member with its value, the server side is proven, and every remaining change belongs in the gateway configuration and the consumer.
One boundary holds regardless: a structure reassembled from separate messages is an informational data path. No interlock, stop function or personnel-protective alarm may depend on it.
Questions asked
Can I decode the ExtensionObject body myself in the consumer?
Not from this payload. The placeholder message carries the type marker, not the structure's encoded bytes, so a consumer-side parser has nothing to work on. The bytes exist only inside the OPC UA session, and decoding them there requires the server's dictionary for that structure, which is the very lookup the gateway skipped. Read the member nodes instead.
Do all OPC UA gateways fail on structures this way?
No. Decoding structured types is a client capability, not part of the connection handshake. Any client that reads the server's type dictionary and the structure's encoding description can expand the members, and desktop browsing clients do, which is why the same node looks fine there. Retest with a single structure node after each gateway update rather than assuming the limit is permanent.
Will reading 40 leaf nodes load the OPC UA server more than one struct node?
Barely. Monitored items in one subscription are delivered together in each publish response, so the extra leaf nodes add no publish cycles; what grows is the message count at the broker and the row count in the database. Size those two for leaf count times publishes per hour, and move members to publish-on-change with a deadband when the number climbs.
What if a member is an array of another structure?
An array of scalars is a single variable of a built-in type and needs no dictionary, so it travels as one leaf. An array of structures is an array of ExtensionObjects and hits the same wall one level down, with no leaf to select from outside. Flatten it on the controller side, one structure per element or scalar members carrying an index, and select those leaves.