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.
Client
✓ import { Client } from 'azure-iot-device';
✗ const Client = require('azure-iot-device').Client;
The primary client interface for all Azure IoT transports is `Client` from the `azure-iot-device` package. `clientFromConnectionString` and `clientFromSharedAccessSignature` are static methods on this `Client` class.
Message
✓ import { Message } from 'azure-iot-device';
✗ const Message = require('azure-iot-device').Message;
The `Message` class is fundamental for creating device-to-cloud messages, regardless of the transport chosen. It's imported from the core `azure-iot-device` package.
Http
✓ import { Http } from 'azure-iot-device-http';
✗ const Http = require('azure-iot-device-http').Http;
This `Http` class represents the specific HTTP transport implementation and is passed as an argument to `Client.fromConnectionString` or `Client.fromSharedAccessSignature` from `azure-iot-device`.
clientFromConnectionString
✓ import { clientFromConnectionString } from 'azure-iot-device-http';
✗ const clientFromConnectionString = require('azure-iot-device-http').clientFromConnectionString;
While this method is re-exported directly from `azure-iot-device-http` for backward compatibility, the recommended modern approach for better type safety and consistency is to import `Client` from `azure-iot-device` and use `Client.fromConnectionString(connectionString, Http)`.
Demonstrates how to connect an Azure IoT device using an HTTP connection string, send a device-to-cloud message, and handle incoming cloud-to-device messages. It uses the modern `Client.fromConnectionString` pattern with the `Http` transport.
import { Client, Message } from 'azure-iot-device';
import { Http } from 'azure-iot-device-http';
// Replace with your actual IoT Hub device connection string.
// You can find this in the Azure portal under your IoT Hub -> Devices -> [Your Device] -> Connection string (primary key).
const connectionString: string = process.env.IOTHUB_DEVICE_CONNECTION_STRING || 'HostName=YOUR_HUB.azure-devices.net;DeviceId=YOUR_DEVICE_ID;SharedAccessKey=YOUR_KEY';
if (connectionString.includes('YOUR_HUB')) {
console.warn('Please replace the placeholder connection string with your actual IoT Hub device connection string.');
process.exit(1);
}
const client = Client.fromConnectionString(connectionString, Http);
const connectCallback = (err?: Error): void => {
if (err) {
console.error(`Could not connect: ${err.message}`);
} else {
console.log('Client connected');
const message = new Message('some data from my device via HTTP');
console.log('Sending message:', message.getData());
client.sendEvent(message, (sendErr?: Error) => {
if (sendErr) {
console.error(`Error sending message: ${sendErr.toString()}`);
} else {
console.log('Message sent successfully');
}
});
client.on('message', (msg: Message) => {
console.log('Received message from IoT Hub:', msg.getData().toString());
client.complete(msg, (completeErr?: Error) => {
if (completeErr) {
console.error(`Error completing message: ${completeErr.toString()}`);
} else {
console.log('Message completed');
}
});
});
client.on('error', (error: Error) => {
console.error(`Client error: ${error.message}`);
});
client.on('disconnect', (transportError: Error) => {
console.warn(`Client disconnected: ${transportError?.message || 'Unknown reason'}`);
});
}
};
client.open(connectCallback);
// Keep the process alive for a bit to allow messages to be received
setInterval(() => {}, 1000 * 60 * 60); // Keep alive for 1 hour or until process is killed
Debug
Known issues
breakingNode.js 12 reached end-of-life and is no longer supported. Azure IoT SDKs moved to Node.js 14 as the minimum requirement.fixUpgrade your Node.js runtime environment to version 14.0.0 or higher. The `engines` field in `package.json` specifies `node: ">= 14.0.0"`.
affects: >=1.18.0
gotchaThe Azure IoT SDK for Node.js supports both CommonJS (`require`) and ES Modules (`import`). Using `require` in an ESM context or vice-versa can lead to runtime errors or incorrect symbol resolution.fixFor modern Node.js projects using ES Modules (e.g., `"type": "module"` in `package.json`), use `import { Client, Message } from 'azure-iot-device';` and `import { Http } from 'azure-iot-device-http';`. For CommonJS projects, use `const { Client, Message } = require('azure-iot-device');` and `const { Http } = require('azure-iot-device-http');`. affects: >=1.0.0
breakingThe underlying `azure-iot-http-base` package changed its dependency from `@azure/core-http` to `@azure/core-auth` in a previous release. While `azure-iot-device-http` abstracts this, direct interactions with `azure-iot-http-base` or type conflicts could arise.fixEnsure your project's dependency resolution correctly handles `@azure/core-auth`. If you are directly using functionalities from `azure-iot-http-base`, consult its documentation for updated API surfaces or type definitions.
affects: >=1.12.2
gotchaThe Azure IoT SDKs, including `azure-iot-device-http`, are regularly updated to address dependency vulnerabilities. Running older versions can expose your application to known security risks.fixRegularly update all `azure-iot-*` packages to their latest stable versions. Utilize tools like `npm audit` or `yarn audit` to identify and resolve known vulnerabilities.
affects: <1.14.4 (any older version)
Errors
Common errors & fixes
TypeError: Client.fromConnectionString is not a function
This error typically occurs when `Client` is not correctly imported as a class with static methods, or when attempting to call `Client.fromConnectionString` directly on the `azure-iot-device-http` package (which is a re-export, but less common in modern usage).
fixEnsure you are importing `Client` from `azure-iot-device` as a named import: `import { Client } from 'azure-iot-device';`. Then, pass the `Http` transport when creating the client: `const client = Client.fromConnectionString(connectionString, Http);`. Error: Could not connect: {"error":"Unauthorized"}
The device connection string provided is invalid, expired, or does not correspond to an active device in your Azure IoT Hub, preventing successful authentication.
fixVerify the device connection string in the Azure portal for your specific device. Ensure it's copied correctly, includes `HostName`, `DeviceId`, and `SharedAccessKey` (or `SharedAccessSignature`), and that the device is enabled in IoT Hub.
(node:xyz) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. N Listener added to [Client]. Use emitter.setMaxListeners() to increase limit
This warning indicates that too many event listeners (e.g., for `message`, `error`, `disconnect` events) are being attached to a `Client` instance, often due to creating new client instances or re-attaching listeners in a loop without proper cleanup.
fixEnsure event listeners are attached only once per `Client` instance. If clients are frequently re-initialized, consider reusing an existing client or explicitly removing old listeners with `client.removeListener(eventName, listenerFunction)` before attaching new ones. For rare cases where many listeners are genuinely needed, `client.setMaxListeners(N)` can suppress the warning, but it's often a symptom of a bug.
Audit
Dependencies
azure-iot-devicerequiredThis package acts as a transport for the core `azure-iot-device` SDK, and relies on its client abstraction for device identity and messaging patterns.
azure-iot-http-baserequiredProvides the foundational HTTP client functionalities and authentication mechanisms used by this transport.