Troubleshooting
Fix CODESYS MQTT TLS peer verification handshake failure
Short answer
Enabling peer verification in the MQTT client's TLS context fails because the controller has no trust anchor for the broker's certificate chain. Import the issuing CA certificate into the runtime's trusted certificate area through the security screen; the client identity .pfx does not provide that trust. A TCP_Init error is an earlier socket-layer fault, so check endpoint settings before touching certificates.
On this page
The handshake fails because the CODESYS runtime holds no trust anchor for the broker's certificate chain. With Peer verification enabled in TLSContext, the IIoT library's MQTT client validates the certificate Mosquitto presents, finds no issuing CA in its trusted certificate area, and aborts; the broker logs error:0A000410:SSL routines::ssl/tls alert handshake failure and drops the client with Protocol error. The fix is to import the CA that issued the broker certificate into the controller's trusted certificate area through the Security Screen. The client identity .pfx does not do that job — it proves the controller to the broker, not the broker to the controller. A TCP_Init error is an earlier fault at the socket layer and calls for network checks, not certificates. The sections below separate the two symptoms, isolate the fault, and end with the decision for each case.
What each error tells you #
A TLS-protected MQTT connection passes three stages: the TCP socket opens, TLS authenticates the endpoint, and only then the MQTT CONNECT packet flows. Each stage fails differently and leaves a different trace.
| Trace you see | Stage that stopped | First move |
|---|---|---|
TCP_Init error the moment itfTLSContext is supplied |
Socket never opened; TLS not reached | Broker address, port and reachability — the TLS listener must exist and answer |
error:0A000410:SSL routines::ssl/tls alert handshake failure in the Mosquitto log, then Client disconnected: Protocol error |
TLS certificate exchange | Import the issuing CA into the trusted certificate area |
Connection succeeds with UseTLS enabled and no TLSContext |
Nothing stopped — nothing was verified | Isolation test only; never a production setting |
The alert line deserves its own reading. In TLS, an alert is the fatal abort notice one endpoint sends before dropping the connection, and handshake_failure is alert number 40 in RFC 8446. When Mosquitto logs it, the socket was already open and the exchange died during certificate processing; in this failure the abort came from the client that could not build a chain to a trust anchor. MQTT credentials never entered the picture, because CONNECT only flows after TLS completes. That is why TCP_Init and this alert call for opposite responses: the first fails before certificates matter, the second fails because of them.
Why peer verification needs a CA, not just your .pfx #
Peer verification adds a path-validation decision to the handshake. RFC 5280, the profile for X.509 certificate path validation, requires the validating party to build a path from the certificate the peer presented to a trust anchor it already holds, checking every issuer signature and every validity window along that path. The runtime receives the broker certificate, follows its issuer chain, and searches the trusted certificate area for an anchor the chain reaches. No anchor, no handshake — whatever else was imported.
A .pfx file, the PKCS #12 format, packages the client's own certificate together with its private key. That material answers the opposite question: it identifies the controller when the broker requests client authentication. The two halves do not substitute for each other, and mutual TLS needs both — the CA in the trusted area lets the controller authenticate the broker, while the .pfx lets the broker authenticate the controller.
Trust also has a broker-side half: the broker must present a complete chain its clients can walk, and note on broker-side TLS trust for browser MQTT clients covers that requirement from the other end of the wire.
Checks that isolate the fault #
- Separate the two failures by timing. A
TCP_Initerror appears the instant the context is supplied; the broker's alert appears only after a socket has connected. Immediate failure points at socket settings; failure after connect points at TLS. - Confirm the port before certificates. Plaintext MQTT listens on 1883 and MQTT over TLS is registered on 8883; a client expecting TLS against the plaintext listener dies at the record layer, not with a clean certificate rejection.
- Run a known-good desktop MQTT client against the same broker and PKI. Success shows the broker presents a usable TLS service; it does not show that the controller holds the same anchors.
- Treat another application on the same controller as unrelated evidence. A separate data-agent component can reference its own certificate store, so its working TLS connection proves nothing about the CODESYS client's trust configuration.
- Open the Security Screen for the controller and look inside the trusted certificate area: the CA that issued the broker certificate must be present there, not only the client's identity certificate.
- Walk the broker's chain end to end — leaf, any intermediate, root. A missing intermediate on the broker fails the handshake exactly like a missing anchor on the controller.
- Check the controller clock against the certificate validity windows, and compare the broker address configured in the client with the identity the broker certificate carries.
When the suspicion moves to the broker half — listener setup, chain presentation, client authentication — the guide on running a secure Mosquitto MQTT lab broker with Node-RED documents that configuration.
Worked example: the validity window against the controller clock #
Illustrative PKI, not a measurement: a root CA valid from 2024-01-01 through 2034-01-01, which is 10 years containing three leap days (2024, 2028, 2032), so 3,650 + 3 = 3,653 days. It issues the broker certificate on 2025-06-01 for 365 days, and 2025 spans exactly 365 days, so the certificate expires on 2026-06-01. The date check passes only while the controller's clock reads a day inside that 365-day window. A clock reading 2026-06-02 fails as expired; 2025-05-31 fails as not yet valid. A controller with a dead backup clock that boots at its build date sits years outside the window and fails the handshake exactly like a missing anchor. The window moves with the lifetime your CA policy chooses; the clock must sit inside it whatever the length.
Import the CA and re-enable verification #
- Identify the CA that issued the Mosquitto broker certificate. With a two-tier PKI, collect the whole path — leaf, intermediate, root — before touching the controller.
- Open the Security Screen for the target controller and import the issuing CA into the trusted certificate area; imported certificates become visible on the devices tab, which confirms the anchor landed.
- Keep the client
.pfxloaded when the broker requests client certificates. - Point the MQTT function block at
itfTLSContextand enablePeer verificationin that context. - Reconnect with the Mosquitto log open and watch for the alert line.
- Restart the runtime or controller and connect again, so the result does not depend on state held in memory.
One shortcut fails here on purpose. A controller-side command that downloads a public CA bundle into the operating system's certificate directory has cleared TLS errors for other applications, but a public bundle contains no private CA, and writing the OS store does not establish that the CODESYS runtime reads that location. The private CA goes in through the Security Screen, into the area the runtime consults.
Verify the corrected connection #
| Test | Pass condition | What it proves |
|---|---|---|
Reconnect with Peer verification on |
Connection holds, no alert in the broker log | The controller accepted the presented chain and identity |
| Broker log over a full shift | No handshake failure alert and no Protocol error disconnect |
TLS completes instead of dying in certificate processing |
| Publish and subscribe exchange | The function block reaches its connected state and data flows | TCP, TLS and MQTT all finished their stages |
| Negative test | A broker certificate signed by an unknown CA is refused | Peer verification is active, not silently bypassed |
One rule stands even when it is inconvenient: leave Peer verification enabled after the fix, because an encrypted link without broker authentication accepts any endpoint that answers on the port, which is exactly the exposure TLS exists to remove.
The decision for each symptom #
Peer verificationon and the broker logs the TLS alert: import the CA that issued the broker certificate into the trusted certificate area, keep the.pfx, reconnect, and confirm with the negative test.itfTLSContextsupplied andTCP_Initappears: fix the socket path first — broker address, the TLS listener rather than the plaintext listener, reachability — then return to certificates.UseTLSalone connects: keep it as an isolation test only. The production configuration isitfTLSContextwithPeer verificationand an imported anchor.
Once the handshake holds, the same link is ready to carry plant data; the guide on bridging OPC UA PLC data to MQTT with an edge PC starts from exactly that working broker connection.
Questions asked
What clock does the runtime use to judge certificate validity?
Certificate validation compares each certificate's validity window against the controller's own clock, not the engineering laptop's. A controller whose time was never synced or whose clock lost its backup can boot years off, which makes a valid certificate read as expired or not yet valid and aborts the handshake like a missing anchor. Fix the time source, confirm the date, and retest before you regenerate any certificate.
Do I import the root CA, the intermediate, or both?
Import the certificate that completes the path from the broker certificate to your trust anchor. With a two-tier PKI, the broker must present its intermediate together with the server certificate, and the controller's trusted area must hold the root the path lands on. A missing intermediate on the broker fails the same way as a missing root on the controller, so check both halves before replacing anything.
Why does the connection still fail when the chain is trusted and the dates are fine?
Peer verification includes an identity check, not only chain building: the name the client dials must match the identity in the broker certificate's subject or subject alternative name. A certificate issued for mqtt.plant.example fails if the client connects by raw IP address or by a different alias, even though the chain validates. Match the configured broker address to the certificate's name, or issue the broker certificate with both names.
Can one CA sign both the broker certificate and the client certificates?
Yes. A single CA can issue the broker certificate and every client certificate, and the same root then serves both ends: the controller holds it in the trusted area to authenticate the broker, and the broker's trust store holds it to authenticate clients. One shared CA keeps a small PKI simple; separate issuing CAs let you revoke the client population without touching broker trust.
How do I prove peer verification is still active after the fix?
Run a negative test: point the client at a broker certificate signed by a CA that is not in the trusted area, or temporarily swap the listener certificate, and try again. The handshake must now fail. If the connection still succeeds, peer verification is not wired into the MQTT context and the link is encrypted without authenticating the broker, which is the state the fix started from.