Errors & exceptions
Modbus exception codes, transport failures, TLS errors, and symptom-led checks.
Errors & exceptions
An error message is useful only when it identifies the layer that rejected the exchange. Busloom preserves connection, transport, framing, protocol-exception, response-validation, decoding, and application errors separately. Start with the first failed transaction, not the last symptom produced by retries.
Standard Modbus exception responses
| Code | Name | Meaning | First check |
|---|---|---|---|
| 01 | Illegal Function | The server does not support or permit the requested function | Address space, device mode, firmware support, gateway restrictions |
| 02 | Illegal Data Address | The requested address or complete range is not valid | PDU/documentation conversion, address space, quantity, multi-register continuation words |
| 03 | Illegal Data Value | A request field or write payload is invalid | Quantity limits, encoded value, mask, device-specific accepted range |
| 04 | Server Device Failure | The server failed while attempting the operation | Device diagnostics, operating state, retry only after understanding impact |
| 05 | Acknowledge | A long-running operation was accepted but is not complete | Vendor workflow and documented follow-up request |
| 06 | Server Device Busy | The server cannot handle the request now | Poll rate, competing masters, device program/flash operation |
| 08 | Memory Parity Error | The server detected a memory consistency error | Device health and vendor service guidance |
| 0A | Gateway Path Unavailable | A gateway cannot establish the downstream route | Gateway channel, downstream bus, route configuration |
| 0B | Gateway Target Failed to Respond | The gateway route exists but the target did not answer | Downstream Unit ID, wiring, serial framing, target power |
An exception is a valid Modbus response: it proves that the peer parsed enough of the request to reject it. Raw Traffic shows the exception function with its high bit set and the one-byte exception code. Do not classify it as a timeout or malformed response.
Transport and validation failures
| Failure | What Busloom observed | Likely checks |
|---|---|---|
| Serial port unavailable | The operating system could not open the path | Correct adapter/path, permission, driver, cable presence, competing process |
| Connection refused | The host actively rejected the TCP connection | Correct IP and port, service enabled, firewall policy |
| Network unreachable | The operating system has no route to the host | Interface, subnet, VLAN/VPN, gateway, host address |
| Timeout | No complete compliant response arrived before the attempt deadline | Unit ID, framing, route, device load, then timeout/retry values |
| CRC error | An RTU frame arrived with a mismatched checksum | Framing, noise, grounding, termination, line bias, duplicate talkers |
| Transaction mismatch | A TCP response did not match the pending transaction identity | Gateway/proxy behavior, interleaved clients, stale or malformed response |
| Function mismatch | The response function is not the requested function or its exception form | Wrong peer, malformed gateway response, captured exact bytes |
| Length / byte-count mismatch | Envelope or PDU sizes disagree with received bytes or requested quantity | Non-compliant device, partial frame, gateway corruption |
| Decode unavailable | Required continuation words are missing or the bytes cannot represent the configured value | Read Plan coverage, data type width, finite float/value constraints |
TLS failures
| Failure | Meaning | Corrective action |
|---|---|---|
| Unknown issuer / untrusted certificate | The configured trust store cannot build a chain to the server certificate | Select the correct CA certificate; do not use Skip verification as a permanent fix |
| Name mismatch | The server certificate is not valid for the host name used by the profile | Use the intended DNS name or deploy a certificate with the correct subject alternative name |
| Expired / not yet valid | The certificate validity window and workstation time do not overlap | Correct system time or renew/reissue the certificate |
| Pinned certificate changed | The presented certificate fingerprint differs from the locally accepted pin | Stop and verify whether the server was legitimately reprovisioned before accepting a new pin |
| Client certificate rejected | The server did not accept the supplied client identity or role | Certificate/key pair, issuer, EKU, server role mapping, validity |
| Handshake / protocol failure | Peers could not agree on a valid TLS session | Server TLS mode, supported protocol/ciphers, middlebox, exact native error |
Fast symptom map
- Everything is silent on RTU
- Stop scans, confirm one serial framing profile, try Unit-ID discovery, then inspect adapter TX/RX indicators and wiring.
- One range fails inside a working view
- Inspect the generated Read Plan and exception. Split around an illegal gap or reduce quantity before changing the poll interval.
- Raw value is stable but engineering value is wrong
- Keep the connection unchanged. Check space/address, width, byte order, word order, signedness, then scale/offset.
- UI appears stale while traffic continues
- Check whether the list is presentation-paused, whether filters hide new rows, and whether the active source timestamp advances.
- Trend or alarm is empty
- Confirm its tag is numeric/Boolean, the owning source is running, the address span is present, and the selected time window contains samples.
- Update keeps appearing
- Identify Store versus direct channel, confirm the installer/package actually replaced the running version, then reopen and inspect the reported version.
Capture before changing the setup
Stop unrelated traffic
Keep one source or one diagnostic request so transaction attribution is unambiguous.
Record the profile facts
Transport, endpoint, Unit ID, serial framing or TLS verification state—without private-key contents.
Retain one complete attempt
Include TX, RX or timeout, latency, retry number, exception/validation text, and source name.
Save the raw interpretation
For a value problem, include raw words and the complete decode chain rather than only the formatted number.
Export the right artifact
Use a bounded session for runtime evidence and the project only when its configuration is part of the reproduction.