Resolving Ignition Node-RED WebSocket Disconnections

After the compatible gateway module creates the WebSocket servlet successfully, the Node-RED tag subscription can connect without polling through an inject interval or scheduled flow. An immediate Ignition disconnected state accompanied by Map: Error creating servlet node-red-ws points to gateway-side WebSocket initialization, not the tag path, host address, or TLS choice.

How does the WebSocket request travel?

Follow the packet. The Node-RED Tag Read ws node initiates a connection to the Ignition gateway address configured in its server object. TCP carries the request to the selected gateway port. With TLS enabled, the peers negotiate TLS before Node-RED sends the HTTP WebSocket upgrade request. Without TLS, the upgrade request travels directly over the TCP connection. The gateway then routes the request to the module's node-red-ws servlet, which must create a WebSocket channel before tag subscription traffic can begin.

In the reported installation, Node-RED and Ignition ran on the same hardware. 127.0.0.1, localhost, and the machine's network address all worked with non-WebSocket reads. That establishes a working local TCP route, gateway authentication path, and ordinary tag API path. It does not test creation of the separate WebSocket servlet.

Which failure pattern identifies the stopping point?

Layer one first, but stop repeating layer-one experiments after the gateway records a servlet exception. A server-side Java constructor failure occurs after the request has arrived. Switching among loopback, localhost, and the network address cannot repair that runtime mismatch.

Which module combination applies?

The correction depends on both the Ignition gateway version and the gateway-side Node-RED module. The Node-RED palette package and the Ignition gateway module have separate release numbers; treating them as one component obscures the actual compatibility decision.

For an 8.1.25 gateway running module 1.5.12 (b2023021717) and reporting the named NoSuchMethodException, the recommended approach is to replace the gateway module with 1.5.13. Reinstalling the same 1.5.12 build and restarting does not change the incompatible WebSocket construction code.

An 8.1.27 installation with module 1.5.13 (b2023022800) was also reported to disconnect and reconnect every 15-20 sec. That later pattern needs a lifetime investigation; it is not proof that the original servlet-construction defect remains.

Why do polling reads work while WebSockets fail?

A polling read is a bounded request-response transaction. Node-RED connects through the gateway's ordinary API route, requests a tag value or browse result, receives a response, and finishes the exchange. Success proves the address, selected listener, credentials, and tag access are usable for that transaction.

A WebSocket subscription adds two gateway behaviors. First, an HTTP request must upgrade into a WebSocket channel. Second, that channel must stay registered while the gateway sends tag changes asynchronously. The logged call to JettyWebSocketServlet.init failed while initializing the servlet, before a stable subscription channel existed. The nested NoSuchMethodException identifies an API compatibility problem inside channel creation rather than a bad tag address.

The Jetty 9 implementation configured the WebSocket path using both registration and creator setup. Ignition 8.1.25+ moved to Jetty 10 behavior, changing how these servlets and channels were created. Gateway module 1.5.12 addressed part of that migration; 1.5.13 supplied the additional channel setup correction.

The configuration display may show an https:// base address with port 8088 or 8043. A WebSocket session still begins as an HTTP request, so an HTTP-style base URL in an information panel does not by itself prove which scheme was placed on the wire. Determine that from the TLS selection and a connection trace: an insecure WebSocket uses an HTTP upgrade, while a secure WebSocket performs TLS first and then upgrades through the encrypted connection.

How should the gateway-side correction be applied?

1. Record the Ignition version, build, gateway module version, Node-RED nodes version, selected host, selected port, TLS state, and the exact first exception from the gateway log. This separates the known constructor failure from a later heartbeat or timeout event.

2. For 8.1.25+ with the immediate node-red-ws servlet error under gateway module 1.5.12, obtain gateway module 1.5.13 from the module's release channel. Do not substitute a Node-RED palette update for the gateway module correction.

3. Remove the affected gateway module, restart the gateway, install the corrected gateway module, and restart again. Confirm that the module page now reports the intended installed build.

4. Open the WebSocket node and select one known server configuration. Match the host, authentication, and TLS choices already proven by a working read node. Use either the working loopback address or the working network address, not alternating addresses during the same test.

5. If the heartbeat field must be used, enter it, deploy the flow, reopen the node, and verify that the value remains visible. A blank “ “ display means the runtime test has no confirmed heartbeat setting; correct configuration persistence before diagnosing heartbeat timing.

6. Activate one WebSocket tag node and watch the gateway diagnostic log at the same time. This produces a direct time correlation between the client attempt and servlet activity.

The module may appear in trial or incomplete-license state even on a licensed Ignition installation. Licensing and WebSocket initialization are separate checks. The documented license path is to have the Node-RED module added to the existing license through the applicable sales channel, then reactivate the license so the gateway receives the updated entitlement. On Edge, changing the module to report itself as free does not by itself establish that the module is permitted; Edge also applies module eligibility controls.

How is the repair verified?

1. Confirm that the gateway starts with the intended Ignition and Node-RED gateway module versions.

2. Deploy the flow with one active WebSocket tag node. Confirm that Map: Error creating servlet node-red-ws and the NodeREDWebSocketChannel.<init>() exception no longer appear.

3. Observe the node status transition away from Ignition disconnected. A quiet gateway log alone is insufficient if the flow never attempted a connection.

4. Change the subscribed tag through a known valid path and confirm that the WebSocket node emits the new value without an inject node, cron schedule, or manual read.

5. Leave the connection active beyond the previously observed failure interval. Record any disconnect timestamp and compare it with gateway and Node-RED log entries.

The decisive test is event delivery over a persistent channel. A successful one-shot read verifies the tag API, while a received asynchronous tag change verifies servlet creation, upgrade, subscription registration, and the return data path.

What if the node reconnects every 15-20 seconds?

A repeating disconnect followed by reconnection changes the fault boundary. The servlet initialized and at least one WebSocket handshake completed. Investigate what closes the established session.

1. Verify that the heartbeat value survives save and deploy. If the node information still shows “ “, treat the heartbeat as unset rather than assigning a timing meaning to it.

2. Capture logs from both endpoints over one complete 15-20 sec cycle. Classify the first event as a client close, server close, transport reset, TLS error, or inactivity timeout.

3. Because the components may share one machine, test the already-proven loopback path to remove external switches, firewalls, proxies, and address translation from the route. If loopback remains stable while the network address cycles, restore the hops one at a time.

4. If both loopback and the network address cycle, compare the deployed heartbeat setting, gateway log event, and process health at the same timestamp. Repeatedly changing secure and insecure ports without classifying the close event hides the controlling variable.

5. Confirm tag changes continue across multiple intervals. A status that reconnects but misses changes is not a healthy subscription.

FAQ