# Troubleshooting Overview

> Common problems when running MTConnect.NET, and how to read the Agent's logs.

URL: https://www.trakhound.com/docs/mtconnect-net/troubleshooting

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](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/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](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/schema-version-mismatches)** — a consumer requesting `version=2.4` from 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](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/mqtt-tls-handshake)** — 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](https://www.trakhound.com/docs/mtconnect-net/configure/integrations#create-a-self-signed-certificate)), confirm the agent's TLS configuration block points at the right `.pfx` or `.pem` paths, and verify the broker's CA bundle is in the agent's trust store.
- **[Empty `name` attributes on probe DataItems](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/common-error-modes#empty-name-on-probe-dataitems)** — caused by a `Devices.xml` that omits the `name` attribute on a DataItem and relies on the agent to synthesize one. Fix: add an explicit `name` attribute to every DataItem in `Devices.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](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/common-error-modes#asset_count-emitted-as-a-scalar-event-instead-of-a-data_set)** — happens on agents built against very old spec versions where `AssetCountDataSet` did not yet exist. Fix: bump the target spec version in the agent config to v1.7 or later and re-emit the device.
- **[`Devices.xml` validation surprises after a v2.x bump](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/common-error-modes#devicesxml-validation-surprises-after-a-v2x-bump)** — new spec versions add new controlled-vocabulary values and tighten existing ones. Fix: validate `Devices.xml` against the per-version XSDs the agent ships under `schemas/` and resolve each error against the spec's release notes for that version.
- **[Pallet measurement constructors not present](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/common-error-modes#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 `MinimumVersion` of `PalletMeasurement` (and its specializations) to see the version that introduced it.
- **HTTP server port already in use** — the default port `5000` is shared with several other .NET application templates. Fix: change `http-server.port` in `agent.config.yaml`, or stop the conflicting process.
- **Devices not appearing in `/probe`** — the most common cause is a `Devices.xml` parse 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.maximumSize` in `agent.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](https://www.trakhound.com/docs/mtconnect-net#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.xml` that reproduces the symptom.

## See Also

- [Common Errors](https://www.trakhound.com/docs/mtconnect-net/troubleshooting/common-error-modes) — more errors from production deployments, with the symptom, cause, and fix for each.
- [Configure an Agent](https://www.trakhound.com/docs/mtconnect-net/configure/agent-config) and [Configure Modules](https://www.trakhound.com/docs/mtconnect-net/configure/module-config) — the reference for every setting troubleshooting touches.
- [Operate](https://www.trakhound.com/docs/mtconnect-net/configure/operate) — logs, metrics, and health checks of a running agent.
- [Known Divergences](https://www.trakhound.com/docs/mtconnect-net/compliance/known-divergences) — when the agent and the cppagent reference disagree, this page names which one `MTConnect.NET` follows and why.
