OPC UA Client for Node.js

Common errors

• Error: connect ECONNREFUSED ::1:4840

  cause The OPC UA client failed to establish a network connection to the server. This typically means the server is not running, is configured on a different IP address/port, or a firewall is blocking the connection.
  fix Verify that the OPC UA server application is running and listening on the specified `endpointUrl` (e.g., `opc.tcp://localhost:4840`). Check firewall rules on both the client and server machines. Use `telnet` or `nc` to manually test network reachability to the server's IP and port.

• StatusCode: BadSecurityChecksFailed

  cause The client's connection request was rejected due to security policy mismatches, or the server did not trust the client's application certificate.
  fix Ensure the client's application certificate (usually generated automatically or found in a 'PKI/own/certs' folder) is copied to the server's trusted client certificates folder. Alternatively, set `securityMode: MessageSecurityMode.None` and `securityPolicy: SecurityPolicy.None` in `OPCUAClient.create` for unsecure connections (not recommended for production).

• Error: Failed to create session (StatusCode: BadUserAccessDenied)

  cause The client successfully connected to the server, but the server rejected the session activation, often due to invalid user credentials, an unsupported user identity token, or insufficient user rights.
  fix If using username/password authentication, verify the credentials are correct and the server supports this user identity token type on the chosen endpoint. If connecting anonymously, ensure the server's endpoint allows anonymous user access.

• StatusCode: BadNodeIdUnknown

  cause The requested NodeId does not exist on the OPC UA server's address space, or its identifier string is malformed (e.g., incorrect namespace index or string identifier).
  fix Double-check the NodeId string for typos (e.g., `ns=X;i=Y` for numeric, `ns=X;s=StringId` for string). Use an OPC UA client browser tool (like UA Expert) to verify the exact NodeId and its attributes on the target server.

• Error: The connection may have been rejected by server, Err = (Invalid message header detected)

  cause A significant time discrepancy between the client and server machines can cause connection rejections, as OPC UA relies on synchronized timestamps for secure communication and certificate validation.
  fix Ensure the system clocks on both the client and the OPC UA server machines are synchronized, ideally using NTP (Network Time Protocol). A time difference of more than a few minutes can lead to handshake failures.

Warnings

• breaking Version 2.168.0 initiated a full migration of core packages from external utility libraries like `async` and `lodash` to native modern JavaScript patterns. While primarily internal, applications relying on internal types, structures, or indirect behaviors derived from these previous patterns might experience breaking changes if not strictly adhering to the public API.
  Fix: Review your codebase for any non-public API usages, especially those that might have implicitly relied on `async` or `lodash` internal structures. Test thoroughly after upgrading.
• gotcha While node-opcua-client is open-source under the MIT license, comprehensive documentation (e.g., 'NodeOPCUA by Example') and technical support for advanced topics are primarily available to registered members of the NodeOPCUA Subscription or through professional services from Sterfive SAS. Open-source users may find limitations in self-serve resources for complex issues.
  Fix: Be aware of the support model; consider a NodeOPCUA Membership for critical production applications or when extensive documentation and direct support are required. Rely on community forums or Stack Overflow for general questions.
• gotcha OPC UA security relies heavily on X.509 certificates. Improper certificate configuration, issues with trust list management, or misconfigured security policies/modes are common sources of connection failures (e.g., 'BadSecurityChecksFailed'). This is especially true when dealing with self-signed certificates or specific server implementations.
  Fix: Ensure client and server certificates are correctly generated and mutually trusted. Place client certificates in the server's trust list and vice-versa. Verify `securityMode` and `securityPolicy` settings in `OPCUAClient.create` align with the server's configuration. For development, `MessageSecurityMode.None` and `SecurityPolicy.None` can bypass certificate issues.
• gotcha When an OPC UA server operates behind NAT, Docker port-mapping, or a reverse proxy, explicit configuration for 'advertised endpoints' is often necessary. Without it (since v2.165.0), clients might incorrectly discover the server's internal network address instead of its externally accessible one, leading to connection failures.
  Fix: If running an OPC UA server behind a proxy or NAT, configure its 'advertised endpoints' to expose the correct external IP address and port that clients should use for connection. Refer to the server's documentation or node-opcua server documentation for details on this configuration.
• gotcha Occasional issues with session reconnection and subscription recovery can occur after network interruptions or server restarts. Clients might fail to re-establish sessions or subscriptions, leading to a loss of real-time data updates, even if the underlying connection appears to be re-established.
  Fix: Implement robust error handling and retry logic around `createSession` and subscription creation. Consider periodically checking session status and actively recreating subscriptions if `keepalive_failure` or `session_closed` events are received. Ensure client application logic can handle transient disconnections and re-initialization.

Install

• npm install node-opcua-client npm
• yarn add node-opcua-client yarn
• pnpm add node-opcua-client pnpm

Imports

• OPCUAClient
  wrong:

  const OPCUAClient = require('node-opcua-client').OPCUAClient;

  correct:

  import { OPCUAClient } from 'node-opcua-client';

  The library primarily uses ES Module syntax and ships TypeScript types. While CommonJS might work, ESM is the recommended and optimized approach for modern Node.js development, especially since v2.168.0's internal modernization.
• ClientSession
  wrong:

  import { ClientSession } from 'node-opcua-client/dist/schemas';

  correct:

  import { ClientSession } from 'node-opcua-client';

  Import core classes directly from the main package. Avoid importing from internal paths like 'dist/schemas' as these are not part of the public API and can change without notice.
• MessageSecurityMode, SecurityPolicy, AttributeIds
  wrong:

  import * as opcua from 'node-opcua-client'; const mode = opcua.MessageSecurityMode.None;

  correct:

  import { MessageSecurityMode, SecurityPolicy, AttributeIds } from 'node-opcua-client';

  Named imports are preferred for specific enums and constants, providing better tree-shaking and clarity. Direct object access from a wildcard import is less efficient.

Quickstart

Demonstrates how to connect to an OPC UA server, create a session, and read a value from a well-known NodeId (Server_ServerStatus_CurrentTime).

import {
    OPCUAClient,
    MessageSecurityMode,
    SecurityPolicy,
    AttributeIds
} from "node-opcua-client";

async function main() {
    // Use process.env.OPCUA_SERVER_ENDPOINT_URL for flexibility, fallback to localhost
    const endpointUrl = process.env.OPCUA_SERVER_ENDPOINT_URL ?? "opc.tcp://localhost:4840";
    
    // Create an OPC UA client instance
    const client = OPCUAClient.create({
        endpointUrl: endpointUrl,
        securityMode: MessageSecurityMode.None, // No security for simplicity (dev/test)
        securityPolicy: SecurityPolicy.None, // No security policy
        connectionStrategy: {
            maxRetry: 10,
            initialDelay: 2000,
            maxDelay: 10 * 1000
        }
    });

    try {
        // Connect the client to the OPC UA server
        await client.connect(endpointUrl);
        console.log("Client connected to endpoint:", endpointUrl);

        // Create a session with the server
        const session = await client.createSession();
        console.log("Session created with ID:", session.sessionId.toString());

        // Define the NodeId to read (e.g., Server_ServerStatus_CurrentTime)
        const nodeIdToRead = "ns=0;i=2258"; 
        
        // Read the value of the specified node
        const dataValue = await session.read({
            nodeId: nodeIdToRead,
            attributeId: AttributeIds.Value
        });
        console.log(`Value of ${nodeIdToRead}: ${dataValue.value.value}`);

        // Close the session and disconnect the client
        await session.close();
        console.log("Session closed.");

        await client.disconnect();
        console.log("Client disconnected.");

    } catch (err) {
        console.error("An error occurred during OPC UA operations:", err);
        process.exit(1);
    }
}

main();