ERR_MODULE_NOT_FOUND for standard devices (e.g., OnOffPluginUnitDevice) due to incomplete "exports" map

[aleteck]

Hello,

I'm reporting a bug that makes it impossible to use many standard device types after a fresh installation of @matter/main from npm.

While basic components like OnOffLightDevice can be imported and used successfully, other standard components like OnOffPluginUnitDevice, WindowCoveringDevice, and various behaviors (ScenesServer, ModeSelectServer) cannot be imported, resulting in an ERR_MODULE_NOT_FOUND error.

The root cause appears to be an incomplete "exports" map in the package.json of the published npm package. The compiled JavaScript files for these devices physically exist in the dist folder, but they don't seem to be exposed through the package's public API.

1. Set up a new Node.js project:

mkdir matter-test && cd matter-test
npm init -y
# Ensure the project is treated as an ES Module
npm pkg set type="module"

2. Install the latest @matter/main:

npm install @matter/main

3. Create a file test.js to demonstrate the issue:

// test.js
console.log("Attempting to import devices...");

try {
    // This import works as expected.
    const { OnOffLightDevice } = await import("@matter/main/devices/on-off-light");
    console.log("✅ SUCCESS: OnOffLightDevice imported successfully.");
} catch (e) {
    console.error("❌ ERROR: Failed to import OnOffLightDevice.");
}

try {
    // This import fails, even though the physical file exists in the dist folder.
    const { OnOffPluginUnitDevice } = await import("@matter/main/devices/on-off-plugin-unit");
    console.log("✅ SUCCESS: OnOffPluginUnitDevice imported successfully.");
} catch (e) {
    console.error("❌ ERROR: Failed to import OnOffPluginUnitDevice.", e);
}

4. Run the script: node test.js

Expected Behavior
Both imports should succeed, as both OnOffLightDevice and OnOffPluginUnitDevice are standard Matter device types.

Actual Behavior
The script fails on the second import with an ERR_MODULE_NOT_FOUND error:

Attempting to import devices...
✅ SUCCESS: OnOffLightDevice imported successfully.
❌ ERROR: Failed to import OnOffPluginUnitDevice. Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../node_modules/@matter/main/dist/esm/forwards/devices/on-off-plugin-unit.js' imported from ...

root@myhome:/opt/matter-test# node test.js
Attempting to import devices...
✅ SUCCESS: OnOffLightDevice imported successfully.
❌ ERROR: Failed to import OnOffPluginUnitDevice. Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/opt/matter-test/node_modules/@matter/main/dist/esm/forwards/devices/on-off-plugin-unit.js' imported from /opt/matter-test/test.js
    at finalizeResolution (node:internal/modules/esm/resolve:257:11)
    at moduleResolve (node:internal/modules/esm/resolve:913:10)
    at defaultResolve (node:internal/modules/esm/resolve:1037:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:650:12)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:599:25)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:582:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:241:38)
    at onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:542:36)
    at TracingChannel.tracePromise (node:diagnostics_channel:337:14)
    at ModuleLoader.import (node:internal/modules/esm/loader:541:21) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///opt/matter-test/node_modules/@matter/main/dist/esm/forwards/devices/on-off-plugin-unit.js'
}

Analysis & Additional Context
This issue is confusing because a find command confirms the physical files do exist in the installed package:

# find ./node_modules -name "*on-off-plugin-unit.js"
./node_modules/@matter/main/dist/esm/forwards/devices/on-off-plugin-unit.js
... (and other locations)

The TypeScript declaration files (.d.ts) also exist, allowing IDEs to provide autocompletion, but the runtime resolution fails. This strongly suggests the issue is not with the library's build process creating the files, but with the package.json "exports" map not being updated to include the paths for these modules.

This problem forces users into workarounds (e.g., using multiple OnOffLightDevice endpoints to simulate other devices) instead of using the correct, semantically appropriate device types.

Could the maintainers please verify if the "exports" map in the published npm package is complete? Is there another officially supported way these devices should be imported?

Thank you for your work on this project.

[Apollon77]

Thanks for reporting it. Thats indeed a strange thing. and yes the files are there and the exports should also be correct:

"./devices/*": {
            "import": {
                "types": "./dist/esm/forwards/devices/*.d.ts",
                "default": "./dist/esm/forwards/devices/*.js"
            },
            "require": {
                "types": "./dist/cjs/forwards/devices/*.d.ts",
                "default": "./dist/cjs/forwards/devices/*.js"
            }
        },

I also use this way of importing in several projects - but yes all with a typescript build process around it.

Can you please try to import the files not dynamically with await but on top of the file - just to see if this makes a difference?

@lauckhart any idea?

[aleteck]

Hi, thank you for the suggestion.

I have updated the test script to use static imports at the top of the file as you requested. Unfortunately, the result is the same. The script still fails with ERR_MODULE_NOT_FOUND when trying to import OnOffPluginUnitDevice.

Here is the updated test script:

// test.js (with static imports)
import { OnOffLightDevice } from "@matter/main/devices/on-off-light";
import { OnOffPluginUnitDevice } from "@matter/main/devices/on-off-plugin-unit";

console.log("Static imports attempted.");
console.log(`✅ OnOffLightDevice imported successfully: ${OnOffLightDevice.name}`);

This confirms the issue is not related to the import style. It seems the module is not correctly exposed in the package's "exports" map for a standard Node.js environment. For now, I will have to stick to a workaround using only OnOffLightDevice.

Thanks again for your help.

[Apollon77]

Hm ... according to the file you need to use "on-off-plug-in-unit" because the class is called OnOffPlugInUnitDevice ... Please fix that and you should be fine :-)

[aleteck]

Hi,

Thank you for the suggestion about the typo in the import path (plug-in vs plugin). You were absolutely right, and correcting it has solved the initial ERR_MODULE_NOT_FOUND error! This is great progress.

However, this has uncovered a new, more subtle issue. When we use the correct import path, we now get a different error:
SyntaxError: The requested module '@matter/main/devices/on-off-plug-in-unit' does not provide an export named 'OnOffPluginUnitDevice'

To diagnose this, we ran a small inspection script to see what the module actually exports:

Inspection Script (test.js):

import * as DeviceModule from "@matter/main/devices/on-off-plug-in-unit";

console.log("Inspecting the exports for 'on-off-plug-in-unit':");
console.log(DeviceModule);

Output::

Inspecting the exports for 'on-off-plug-in-unit':
[Module: null prototype] {
  OnOffPlugInUnitDevice: {
    name: 'OnOffPlugInUnit',
    deviceType: 266,
    // ... plus other properties like requirements, behaviors, etc.
  },
  OnOffPlugInUnitDeviceDefinition: { /* ... */ },
  OnOffPlugInUnitRequirements: { /* ... */ }
}

As the output shows, the module does not export a usable class named OnOffPluginUnitDevice. Instead, it exports a configuration object with that name.

This appears to be the root of the SyntaxError. While OnOffLightDevice seems to be exported as a ready-to-use class, OnOffPluginUnitDevice is exported as a definition object, which makes it impossible to import with { OnOffPluginUnitDevice } and use in the Endpoint constructor in the same way.

Is there a specific factory function or a different pattern we should use to create a device instance from this definition object? We feel very close to the solution but are missing this final step.

Context:

To provide more context on what we are trying to achieve, here is a description of the simulated device:

The goal is to create a virtual Matter device that acts as a bridge for an MQTT-controlled load controller connected to an oven.

The device requires two separate functions, which we would ideally like to expose within a single tile in the SmartThings app:

Main Power: A primary On/Off toggle that controls the oven's main power relay.

Exclude Mode: A secondary On/Off toggle that controls an "exclude" state. This function is used to temporarily exclude the oven from an automated load management system in the house.

Our main challenge has been finding the right Matter Device Type and/or composition of Behaviors in matter.js that can correctly model this and be rendered as a single, multi-function device by a controller like SmartThings.

Our attempt to use OnOffPluginUnitDevice as a base, combined with an OnOffServer (for Power) and a ModeSelectServer (for the Exclude mode), seemed like the perfect solution, but as shown above, we are blocked by the module export issue.

Given this use case, could you suggest a standard device type or an example that would be the best fit for this kind of "two-function" load controller?

We are looking for the most semantically correct and reliable approach. Any example you could point to would be incredibly helpful. Thank you!

[Apollon77]

Yes and now read my last meassage again please

SyntaxError: The requested module '@matter/main/devices/on-off-plug-in-unit' does not provide an export named 'OnOffPluginUnitDevice'

Hm ... according to the file you need to use "on-off-plug-in-unit" because the class is called OnOffPlugInUnitDevice ... Please fix that and you should be fine :-)

Notice the captial I in PlugIn ... and thats the whole source.

We exactly use the names from the Matter Spec and the devce is called there the same

[Apollon77]

So in your import the class name AND the import path was both wrong. So you also need to change both

[aleteck]

Hi @Apollon77,

First, my apologies for the oversight on the typo. After running so many tests, I completely missed the case sensitivity in PlugIn. Thank you for pointing it out – the import now works correctly.

My goal is to model a custom load controller for an oven. I need to expose two separate On/Off functions within a single tile in the SmartThings app:

Main Power: A primary On/Off switch that controls the oven's main physical power relay.

Exclude: A secondary On/Off switch used to inhibit an external overload control system. When "Exclude" is ON, the oven is temporarily removed from the house's automated load management system.

To achieve this, I tried creating a "hybrid" device using an Aggregator. My thinking was that the first endpoint (OnOffPlugInUnitDevice) would set the main icon, while the second (OnOffLightDevice) would appear as a secondary control. Here is the code for that attempt:

Current Code (oven-hybrid-attempt.js)

/**
 * oven-hybrid-attempt.js
 * GOAL: Create a single device tile with a socket icon, containing two separate switches.
 * HYBRID STRATEGY:
 * 1. The first endpoint ("Power") is an OnOffPlugInUnitDevice to set the main icon 🔌.
 * 2. The second endpoint ("Exclude") is an OnOffLightDevice, which we know SmartThings always shows.
 * OBSERVED RESULT: This creates two separate tiles in SmartThings: one socket and one light bulb.
 */

import { ServerNode, Endpoint, DeviceTypeId, VendorId } from "@matter/main";
import { OnOffPlugInUnitDevice } from "@matter/main/devices/on-off-plug-in-unit";
import { OnOffLightDevice } from "@matter/main/devices/on-off-light";
import "@matter/main/devices";
import mqtt from "mqtt";

// --- Configuration ---
const MQTT_URL = "mqtt://192.168.1.150";
const MQTT_COMMAND_TOPIC = "scs/generic/set/B7";
const MATTER_PORT = 5544;
const MATTER_PASSCODE = 20202021;
const MATTER_DISCRIMINATOR = 3844;

async function run() {
  console.log("▶️  Starting HYBRID test for Oven...");

  const device = await ServerNode.create({
    id: "node-oven-hybrid-test",
    network: { port: MATTER_PORT },
    commissioning: { passcode: MATTER_PASSCODE, discriminator: MATTER_DISCRIMINATOR },
    productDescription: {
      name: "Oven (Hybrid Test)",
      deviceType: DeviceTypeId(0x000e), // Aggregator
    },
    basicInformation: {
      vendorName: "Matter-MQTT Bridge",
      vendorId: VendorId(0xFFF1),
      nodeLabel: "Oven (Hybrid Test)",
      productName: "Oven Load Control (Hybrid)",
      productId: 0x8011,
    },
  });

  const mqttClient = mqtt.connect(MQTT_URL, { reconnectPeriod: 3000 });
  mqttClient.on("connect", () => console.log(`[MQTT] Connected to ${MQTT_URL}`));

  // Modified function to accept the device class as a parameter
  const createSwitchEndpoint = async (name, DeviceClass, onPayload, offPayload) => {
    const endpoint = new Endpoint(DeviceClass, { id: name.toLowerCase() });

    endpoint.events.onOff.onOff$Changed.on(async (isOn) => {
      const payload = isOn ? onPayload : offPayload;
      const status = isOn ? "ON" : "OFF";
      console.log(`[MATTER] '${name}' (${DeviceClass.name}) set to ${status}. Sending '${payload}' to MQTT.`);
      mqttClient.publish(MQTT_COMMAND_TOPIC, payload);
    });
    
    await device.add(endpoint);
    console.log(`[MATTER] Created endpoint: ${name} (as ${DeviceClass.name})`);
  };

  // Creating the two switches with DIFFERENT CLASSES
  await createSwitchEndpoint("Power", OnOffPlugInUnitDevice, "061301", "061304");
  await createSwitchEndpoint("Exclude", OnOffLightDevice, "061300", "06130F");
  
  await device.run();
  console.log("✅ HYBRID test for oven started. Please pair.");

  process.on("SIGINT", async () => { await device.close(); process.exit(0); });
}

run().catch(console.error);

Unfortunately, this configuration results in two separate tiles on the SmartThings dashboard: one with a socket icon and another with a light bulb icon. It doesn't group them into a single device as hoped.

My question is: What is the correct matter.js pattern to create a custom device that is recognized by controllers as a single entity but provides multiple, independent On/Off controls inside it (similar to a power strip)?

Should I be using a different root device type, extending a base class, or composing behaviors in a specific way? Any example or guidance would be incredibly helpful.

Thanks again for your support.

[Apollon77]

Ok I converted it into a discussion now :-)

It seems you have a misunderstanding. When you use an Aggregator then you provide a bridge. This means each "bridged node" inside the aggregator is indeed seen as a single bridged device. But effectively your code does not show that you use an Aggregator?

SO what you have build it technically correct for your purpose - you have build a "composed device". But now you come exactly to the point you see ... How ecosystems present such composed devices is completely up to them. I know that Apple Home would combine the two controls on one tile, but most others simply don't do this. So basically ... No clear way where you can expect any defined behavior. Sorry