Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OPCUAServer
✓ import { OPCUAServer } from 'node-opcua';
✗ import OPCUAServer from 'node-opcua-server';
The `OPCUAServer` class is generally imported from the umbrella `node-opcua` package, which re-exports server components, despite `node-opcua-server` being the specific module.
DataType
✓ import { DataType } from 'node-opcua';
✗ import { DataType } from 'node-opcua-data-model';
Common OPC UA data types are typically re-exported from the main `node-opcua` package for convenience. For specific enum values like `DataType.Boolean`, access via `DataType` import.
Variant
✓ import { Variant } from 'node-opcua';
✗ import { Variant } from 'node-opcua-data-value';
The `Variant` class, used for wrapping values with their data type, is commonly re-exported from the main `node-opcua` package.
StatusCodes
✓ import { StatusCodes } from 'node-opcua';
Standard OPC UA status codes are re-exported from the main `node-opcua` package.
NodeId
✓ import { NodeId } from 'node-opcua';
The `NodeId` class, for uniquely identifying nodes in the address space, is commonly re-exported from the main `node-opcua` package.
This quickstart code demonstrates how to create a basic OPC UA server, define a custom address space with a dynamic temperature variable, and handle graceful shutdown. It uses `node-opcua` for all core functionalities, including server instantiation, node creation, and data type handling.
import { OPCUAServer, DataType, Variant, StatusCodes, NodeId } from 'node-opcua';
const server = new OPCUAServer({
port: 4840, // default OPC UA port
resourcePath: '/UA/MyAwesomeServer',
buildInfo: {
productName: 'My Awesome OPCUA Server',
buildNumber: '7658',
buildDate: new Date(2026, 3, 19)
}
});
async function startServer() {
await server.start();
console.log('Server started and listening on', server.endpoints[0].endpointUrl);
console.log('Press Ctrl+C to stop the server.');
server.on('post_initialize', () => {
// Define the address space
const addressSpace = server.engine.addressSpace;
if (!addressSpace) {
console.error('Address space not available.');
return;
}
const namespace = addressSpace.get = addressSpace.registerNamespace('http://mynamespace.com/UA/MyAwesomeServer/');
const device = namespace.addObject({
organizedBy: addressSpace.rootFolder.objects,
browseName: 'MyDevice'
});
let temperature = 25.0;
namespace.addVariable({
componentOf: device,
nodeId: 's=Temperature',
browseName: 'Temperature',
dataType: DataType.Double,
value: {
get: () => new Variant({
dataType: DataType.Double,
value: temperature
})
}
});
// Simulate temperature changes
setInterval(() => {
temperature = 20 + 10 * Math.sin(Date.now() / 10000); // Oscillation between 10 and 30
}, 1000);
console.log('Address space initialized with a Temperature variable.');
});
process.on('SIGINT', async () => {
console.log('Caught interrupt signal, shutting down server...');
await server.shutdown();
console.log('Server shut down.');
process.exit(0);
});
}
startServer().catch(console.error);
Debug
Known issues
breakingVersion 2.168.0 migrated core packages from `async` and `lodash` to native JavaScript patterns. While primarily internal, applications relying on implicit availability or specific behaviors of these dependencies within `node-opcua` might encounter unexpected issues or require adjustments.fixReview your codebase for any direct or indirect reliance on `async` or `lodash` utilities that might have been supplied by older `node-opcua` versions. Ensure your application explicitly manages its own `async`/`lodash` dependencies if needed.
affects: >=2.168.0
breakingThe certificate management architecture has undergone several overhauls (v2.164.2, v2.167.0, v2.168.0), including `TrustListClient.addCertificate` now accepting certificate chains and a new typed event system for post-handshake notifications. Existing code for certificate handling or event listeners might need updates.fixConsult the latest documentation for `OPCUACertificateManager` and server event handling. Update certificate provisioning logic to account for chain acceptance. Review event listeners, especially for security-related notifications like `channelSecured`.
affects: >=2.164.2
gotchaFor deployments behind Docker, NAT, or reverse proxies, correctly configuring 'Advertised Endpoints' (introduced in v2.165.0) is crucial. Incorrect configuration will lead to clients being unable to connect or browse the server, as the server advertises incorrect connection details.fixEnsure the `OPCUAServer` configuration includes `serverInfo.discoveryUrls` and `serverInfo.alternateEndpoints` with the externally accessible IP addresses or hostnames and ports. Set `endpointUrl` correctly if overriding.
affects: >=2.165.0
gotchaMajor performance improvements and OPC UA 1.05 compliance updates, particularly for DataType handling (v2.163.0), might introduce subtle behavioral changes. Applications with complex information models or custom data types should be thoroughly tested.fixPerform comprehensive regression testing, especially for interactions with custom complex data types and large address spaces. Validate data serialization/deserialization if you're dealing with OPC UA 1.05 specific structures or unions.
affects: >=2.163.0
breakingSecurity upgrades, such as the Node.js runtime update to 20.19.6 in v2.159.0, highlight the importance of keeping your Node.js environment updated. Using outdated Node.js versions can expose your application to known vulnerabilities.fixRegularly update your Node.js runtime to the latest LTS version to ensure security and compatibility. Monitor `node-opcua` release notes for recommended Node.js versions.
affects: >=2.159.0 (indirectly)
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::4840
The configured OPC UA server port (default 4840) is already being used by another process on the system.
fixChange the `port` in the `OPCUAServer` constructor to an available port, or stop the conflicting process. On Linux, use `sudo lsof -i :4840` to identify the process.
Bad_SecurityChecksFailed (0x80030000)
The client's certificate is not trusted by the server, or there is a mismatch in security policies/modes, preventing a secure connection.
fixEnsure the client's certificate is added to the server's trust list. Verify that the client and server are configured with compatible `securityMode` (e.g., `None`, `Sign`, `SignAndEncrypt`) and `securityPolicy` (e.g., `None`, `Basic256Sha256`). Regenerate certificates if they are expired or malformed.
Error: Cannot find module 'node-opcua'
The `node-opcua` package is not installed or not resolvable in the current project context.
fixRun `npm install node-opcua` in your project directory. If using a monorepo or specific sub-packages, ensure all dependencies are correctly linked or installed.
Client unable to connect to opc.tcp://my-server-ip:4840/UA/MyAwesomeServer
The server is not accessible at the specified endpoint, possibly due to firewall rules, incorrect IP/hostname, or misconfigured advertised endpoints (especially in Docker/NAT environments).
fixCheck server configuration for `port`, `resourcePath`, and especially `serverInfo.discoveryUrls` and `serverInfo.alternateEndpoints` if running behind NAT or Docker. Verify network connectivity and firewall settings. Ensure the server has started successfully without errors.
Audit
Dependencies
No dependency data recorded yet.