Resolving IOT2050 Node-RED OPC UA Missing Node Type Errors

Problem Overview

On a SIMATIC IOT2050 (article number 6ES7 647-0BA00-1YA2) running IOT2050_IndustrialOS_Service_Stick_V3.2.2, a Node-RED flow that bridges to a SIMATIC S7-1518 PLC over OPC UA fails immediately on deploy. The editor banner reports:

Flow stopped due to missing node type

The missing node classes observed in the flow configuration are:

• OpcUa-Endpoint
• OpcUa-Client
• OpcUa-Item
• ui_tab
• ui_base

The first three are provided by the node-red-contrib-opcua Node-RED package; ui_tab and ui_base are contributed by the node-red-dashboard palette. The combined failure pattern indicates that the OPC UA plugin failed to load at runtime, dragging the dashboard nodes down with it, so the editor surfaces every dependency as a "missing type".

Affected Hardware and Software Stack

Refer to the official SIMATIC IOT2050 product page and operating instructions on Siemens Industry Online Support for the canonical device description and download area for IndustrialOS service sticks.

Root Cause: Node.js Runtime Incompatibility

The fundamental cause is a Node.js major-version mismatch. The node-red-contrib-opcua package at version 0.2.339 (and every release on the 0.2.x and 0.3.x lines that followed) requires a Node.js runtime newer than the v12 LTS that ships with IndustrialOS V3.2.2. When the Node-RED loader tries to require() the plugin's compiled native bindings, the engine check throws and the module is never registered. Node-RED then reports every node class defined in that package as a missing type.

Specific failure chain:

1. Operator updates the palette in Node-RED → node-red-contrib-opcua is upgraded to 0.2.339.
2. Node-RED restarts and tries to load the new module against the bundled Node.js v12.22.12 runtime.
3. The plugin's engines.node constraint is violated. The native OPC UA stack (built against newer V8 API) aborts during require().
4. Node-RED's runtime registry is missing five node types, so the flow is suspended with the missing-type error.

Diagnostic Procedure

Run the following sequence on the IOT2050 console or over SSH. Capture each output for the support ticket.

1. Confirm Node.js version

   node -v
   npm -v

   Expected on IndustrialOS V3.2.2 out of the box: v12.22.12.

2. Confirm Node-RED version and user data directory

   node-red --version
   node-red --help

3. Inspect the loaded palette

   ls -la ~/.node-red/node_modules | grep -E 'opcua|dashboard'

   Verify whether node-red-contrib-opcua and node-red-dashboard are present in the user data directory.

4. Reproduce the failure in safe mode

   node-red --safe

   Safe mode disables all third-party nodes. If the flow deploys in safe mode, the failure is a plugin load error, not a flow JSON error.

5. Read the runtime log

   tail -n 200 ~/.node-red/node-red.log | grep -iE 'opcua|missing|error'

   Look for lines such as Error: The module '...' was compiled against a different Node.js version. This is the smoking gun.

6. Check apt for available Node.js

   apt-cache policy nodejs

   This will confirm that the IOT2050 apt mirror is pinned to Node.js 12 packages, which is why a simple upgrade cannot lift the runtime.

Resolution Path A: Migrate to IndustrialOS 4.2.1 (Recommended)

Siemens provides a pre-release of IndustrialOS 4.2.1 for the IOT2050 that ships with Node.js v18.19.0, the LTS line supported by the current node-red-contrib-opcua releases. This is the cleanest path because the OS image also refreshes the entire Node-RED container dependencies and the underlying Debian base packages.

1. Request the pre-release image from Siemens technical support for IOT2050. The pre-release is delivered out-of-band and is not in the public download center at the time of writing.
2. Validate project requirements: IndustrialOS 4.2.1 pre-release does not support Secure Boot. Confirm with the plant security officer that UEFI Secure Boot is not mandated for this device, or accept the risk and disable Secure Boot in the BIOS before booting the new image.
3. Back up the existing user data directory:

   sudo systemctl stop node-red
   sudo tar czf /tmp/node-red-backup.tar.gz /home/iot2050/.node-red

4. Flash the new service stick and boot. IndustrialOS 4.2.1 will mount /var/lib/iot2050 from a new image but preserve the existing partition if you choose to retain user data during the first-boot wizard.
5. Verify the runtime:

   node -v   # expect v18.19.0
   node-red --version

6. Restore the flow export:

   node-red-admin install [email protected]
   node-red-admin install node-red-dashboard

7. Deploy the flow and confirm the editor banner is clear.

Resolution Path B: Manual Node.js Upgrade on IndustrialOS V3.2.2

If a full image migration is not possible because of Secure Boot or change-control constraints, upgrade the Node.js runtime in place using the NodeSource distribution. This path is unsupported by Siemens and must be documented in the change ticket.

1. Install prerequisites:

   sudo apt-get install -y ca-certificates curl gnupg

2. Add the NodeSource repository for Node.js 18 LTS (Bullseye track matches IndustrialOS V3.2.2):

   curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
     | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg
   echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_18.x bullseye main" \
     | sudo tee /etc/apt/sources.list.d/nodesource.list
   sudo apt-get update

3. Upgrade Node.js and npm:

   sudo apt-get install -y nodejs
   node -v   # expect v18.x

4. Reinstall the global Node-RED and OPC UA packages so that their native bindings recompile against the new V8 ABI:

   sudo npm install -g --unsafe-perm node-red
   sudo npm install -g --unsafe-perm [email protected]
   sudo npm install -g --unsafe-perm node-red-dashboard

5. Restart the Node-RED service and deploy the flow.

Resolution Path C: Pin node-red-contrib-opcua to a v12-Compatible Release

If neither of the above paths is acceptable (locked image, no Secure Boot exemption, regulated environment), the OPC UA plugin can be downgraded to the last release that still supports Node.js 12. This is a tactical workaround, not a long-term solution.

1. Identify the last compatible release. The 0.2.x line dropped Node.js 12 support progressively; the final v12-capable build is typically in the early 0.2.3xx range. Inspect the package's engines field across versions:

   npm view [email protected] engines
   npm view [email protected] engines

2. Pin the working version in the user data directory:

   cd ~/.node-red
   npm install node-red-contrib-opcua@<last-v12-build> --save

3. Lock the version to prevent auto-upgrade by editing ~/.node-red/package.json so that the dependency line has no ^ or ~ prefix.
4. Disable palette auto-update in ~/.node-red/settings.js:

   editorTheme: {
     projects: { enabled: false }
   },
   palette: { editable: false }

Verification Steps

After applying any of the three resolution paths, run the following checklist before handing the device back to operations:

1. Confirm Node.js and Node-RED are on the intended versions:

   node -v
   node-red --version

2. Open the Node-RED editor at http://<iot2050-ip>:1880. The banner must read Connected; the missing-type error must be gone.
3. Click each OPC UA node in the flow and confirm the type picker (top right) shows OpcUa-Endpoint, OpcUa-Client, and OpcUa-Item as recognised classes.
4. Trigger a deploy and watch the debug sidebar. Expected: no ReferenceError or compiled against a different Node.js version lines.
5. Verify the OPC UA session against the S7-1518. The S7-1500 OPC UA server is enabled per default in TIA Portal V17 and later, listening on opc.tcp://<plc-ip>:4840:
   • Endpoint URL: opc.tcp://<plc-ip>:4840
   • Security policy: None for the first test, then move to Basic256Sha256 with a server certificate
   • Authentication: Anonymous for the first test, then a configured user in the S7-1500 user management
6. Subscribe to a single tag, force a value change in TIA Portal, and confirm the change appears in the Node-RED debug pane within one polling cycle.

OPC UA Client Configuration for the SIMATIC S7-1518

For a stable link between the IOT2050 Node-RED flow and a SIMATIC S7-1518, configure the OPC UA client nodes as follows. These settings reflect the OPC UA server that the S7-1500 CPU exposes once the option is activated in TIA Portal under Device configuration > OPC UA > Server.

Refer to the SIMATIC S7-1500 OPC UA server manual on Siemens Industry Online Support for the namespace mapping rules and the firmware-specific security policy list.

Troubleshooting Matrix

Best Practices and Prevention

• Pin the Node.js runtime in the IOT2050 documentation. IndustrialOS V3.2.2 = Node.js 12. IndustrialOS 4.x = Node.js 18. Treat any deviation as a configuration drift event.
• Always test a Node-RED palette update on a non-production IOT2050 first. The native bindings of node-red-contrib-opcua recompile on install, and a successful install on a workstation does not guarantee a successful install on the ARM-based IOT2050.
• Snapshot the IOT2050 with the bundled rauc update framework before any manual Node.js upgrade. IndustrialOS supports rauc for A/B partition rollback.
• Maintain a version manifest for the OPC UA plugin. Record the exact node-red-contrib-opcua version, Node.js version, and the S7-1500 firmware version in the change ticket.
• Disable palette auto-update in regulated environments by setting palette.editable: false in settings.js. Operators must raise a change request to update a package.
• When migrating to IndustrialOS 4.2.1, involve the plant security team early. Secure Boot is disabled in the pre-release and the change must be approved and documented before flashing.

FAQ