Common errors when running MTConnect.NET and the fixes that work.
The troubleshooting pages describe each problem the same way:
the symptom (what you see in the logs or on the wire), the cause, the fix, and the prevention that keeps it from coming back.
The categories below summarize them, with a link to the page for each.
Categories
- XSD validation failures — the .NET BCL ships an XSD-1.0 validator, but several MTConnect XSDs use XSD-1.1 assertions.
Symptoms include validation errors on documents that pass against the cppagent reference.
Fix: route validation through the agent's structural validator (the per-class checks in
MTConnect.NET-Common) and treat the XSD validator as advisory for the 1.1-only constructs. - Schema-version mismatches between agent and consumer — a consumer requesting
version=2.4from an agent built against v2.7 receives a v2.4-shaped envelope, but a consumer pinned to a fixed namespace URL sees a mismatch. Fix: have the consumer follow the namespace URL the agent emits in the response root rather than hard-coding it. - MQTT TLS handshake failures — usually a certificate-chain problem when running against AWS IoT, HiveMQ Cloud, or any broker that requires mutual TLS.
Fix: regenerate the certificate chain with OpenSSL (see the OpenSSL guide), confirm the agent's TLS configuration block points at the right
.pfxor.pempaths, and verify the broker's CA bundle is in the agent's trust store. - Empty
nameattributes on probe DataItems — caused by aDevices.xmlthat omits thenameattribute on a DataItem and relies on the agent to synthesize one. Fix: add an explicitnameattribute to every DataItem inDevices.xml; the spec does not require it on every DataItem but consumers often do. - Asset count emitted as a scalar EVENT instead of a DATA_SET — happens on agents built against very old spec versions where
AssetCountDataSetdid not yet exist. Fix: bump the target spec version in the agent config to v1.7 or later and re-emit the device. Devices.xmlvalidation surprises after a v2.x bump — new spec versions add new controlled-vocabulary values and tighten existing ones. Fix: validateDevices.xmlagainst the per-version XSDs the agent ships underschemas/and resolve each error against the spec's release notes for that version.- Pallet measurement constructors not present — the rich-template Pallet measurement types are introduced in newer spec versions.
Fix: confirm the library version supports the spec version you target, and check the
MinimumVersionofPalletMeasurement(and its specializations) to see the version that introduced it. - HTTP server port already in use — the default port
5000is shared with several other .NET application templates. Fix: changehttp-server.portinagent.config.yaml, or stop the conflicting process. - Devices not appearing in
/probe— the most common cause is aDevices.xmlparse error that the agent logs but does not crash on. Fix: check the agent log for the parse error, fix the malformed XML, restart. - Buffer-overflow log messages under load — the agent's sequence buffer has a configurable size and drops the oldest observations when full.
Fix: increase
buffer.maximumSizeinagent.config.yaml, or process the buffer faster via more responsive consumers.
Reading the Agent Logs
The agent writes to stdout by default and to a configurable log file when running as a service.
Log levels: Debug, Info, Warning, Error, Fatal.
Most fixable issues surface at Warning and Error.
To capture the most diagnostic information, set the global log level to Debug temporarily — the volume is high, so do not leave it on in production.
When the Fix Is Not Here
- Check the Guides for the recipe that matches your deployment pattern — the recipe may already work around the issue.
- Open an issue at https://github.com/TrakHound/MTConnect.NET/issues with the agent version, the relevant log lines, and a minimal
agent.config.yaml+Devices.xmlthat reproduces the symptom.
See Also
- Common Errors — more errors from production deployments, with the symptom, cause, and fix for each.
- Configure an Agent and Configure Modules — the reference for every setting troubleshooting touches.
- Operate — logs, metrics, and health checks of a running agent.
- Known Divergences — when the agent and the cppagent reference disagree, this page names which one
MTConnect.NETfollows and why.