Skip to content

Matter.js server doesn't properly handle SIGTERM when started with env var BLUETOOTH_ADAPTER=0 #454

@schildbach

Description

@schildbach

Version

0.5.10

Node.js Version

v22.22.2

Operating System

Docker

Issue Description

When shutting down the Docker container, Docker first sends a SIGTERM to the node process, initiating a graceful shutdown. However, Matter.js server when started with "BLUETOOTH_ADAPTER=0" seems to pick that signal but doesn't shut down. Hence, after 10 seconds the process is killed forcibly (SIGKILL). This yields an exit code of 137 for the container.

I tried extending the grace period to 30 seconds but it didn't change anything.

Steps to Reproduce

  1. docker run -e BLUETOOTH_ADAPTER=0 matterjs-server:0.5.10
  2. wait a bit to let it start
  3. press CTRL-C once
  4. it says "shutting down" in the log but it doesn't
  5. after 10s the container is forcibly stopped by docker and the exit code is 137

Without "-e BLUETOOTH_ADAPTER=0", it works as expected (immediate shutdown and exit code 0).

Server Logs

2026-03-28 14:34:14.673 INFO   MatterServer         Command line: (no arguments)
2026-03-28 14:34:14.676 INFO   MatterServer         Bluetooth enabled (hci-id=0)
2026-03-28 14:34:14.678 INFO   ConfigStorage        Storage location: /data (Directory)
2026-03-28 14:34:14.683 INFO   ConfigStorage        Set config key fabricLabel to HomeAssistant
2026-03-28 14:34:14.689 INFO   ConfigStorage        Set config key nextNodeId to 1
2026-03-28 14:34:14.696 INFO   ConfigStorage        Set config key wifiSsid to undefined
2026-03-28 14:34:14.700 INFO   ConfigStorage        Set config key wifiCredentials to <redacted>
2026-03-28 14:34:14.703 INFO   ConfigStorage        Set config key threadDataset to <redacted>
2026-03-28 14:34:14.706 INFO   ServerIdResolver     Using new server ID format: server-1-fff1
2026-03-28 14:34:14.711 INFO   Controller~ndHandler BLE is enabled
2026-03-28 14:34:14.712 WARN   MatterServer         WebSocket server is listening on all network interfaces. Use --listen-address to restrict access. Ensure your environment (firewall, network) prevents unauthorized access.
2026-03-28 14:34:14.712 INFO   WebSocketC~erHandler Starting server: matter-server/0.5.10 (matter.js/0.17.0-alpha.0-20260326-42b6f59b7)
2026-03-28 14:34:14.728 INFO   ServerNodeStore      Opened server-1-fff1 storage location: /data/server-1-fff1 driver: file
2026-03-28 14:34:14.763 INFO   BaseEventStore       Initialized new volatile event store
2026-03-28 14:34:14.783 INFO   Endpoint             server-1-fff1 ready endpoint#: (unassigned) type: RootNode (0x16, rev 3) behaviors: 💤parts ✓index ✓basicInformation ✓accessControl ✓groupKeyManagement ✓generalCommissioning ✓administratorCommissioning ✓operationalCredentials ✓generalDiagnostics ✓commissioning ✓network 💤productDescription 💤subscriptions 💤sessions ✓events 💤controller ✓descriptor
2026-03-28 14:34:14.792 INFO   DclOtaUpdateService  Initialize OTAUpdateService prod: https://on.dcl.csa-iot.org test: https://on.test-net.dcl.csa-iot.org
2026-03-28 14:34:14.796 INFO   Endpoint             server-1-fff1.ota-provider ready endpoint#: 1 type: OtaProvider (0x14, rev 1) behaviors: ✓otaSoftwareUpdateProvider ✓descriptor ✓softwareupdates
2026-03-28 14:34:14.805 INFO   CertificateAuthority Created new credentials with ID 0
2026-03-28 14:34:14.824 NOTICE Node                 server-1-fff1 going online
noble warning: adapter does not support Bluetooth Low Energy (BLE, Bluetooth Smart).
               Try to run with environment variable:
               [sudo] NOBLE_HCI_DEVICE_ID=x node ...
2026-03-28 14:34:14.841 NOTICE Node                 server-1-fff1 is online
2026-03-28 14:34:14.842 INFO   FabricAccessControl  ACL List updated privilege: 5 authMode: 2 subjects: 112233 targets: null fabricIndex: 1
2026-03-28 14:34:14.849 INFO   FabricAccessControl  ACL List updated privilege: 5 authMode: 2 subjects: 112233 targets: null fabricIndex: 1
2026-03-28 14:34:14.850 INFO   Transaction          Tx ◦reactor<server-1-fff1.operationalCredentials.#handleUpdatedFabric>#23 waiting on ◦offline#20
2026-03-28 14:34:14.855 INFO   FabricAccessControl  ACL List updated privilege: 5 authMode: 2 subjects: 112233 targets: null fabricIndex: 1
2026-03-28 14:34:14.862 INFO   MdnsAdvertisement    Publishing kind: operational service: mdns:2047FEC6DD3B68FA-000000000001B669._matter._tcp.local
2026-03-28 14:34:14.863 INFO   SoftwareUp~teManager Scheduling first OTA update check in 5m 44s
2026-03-28 14:34:14.878 INFO   FabricAccessControl  ACL List updated privilege: 5 authMode: 2 subjects: 112233 targets: null fabricIndex: 1 privilege: 3 authMode: 2 subjects:  targets: { cluster: 41, endpoint: 1, deviceType: null } fabricIndex: 1
2026-03-28 14:34:14.879 INFO   OtaSoftwar~derServer Added ACL entry to allow access to OTA Software Update Provider for anyone in the fabric
2026-03-28 14:34:14.879 INFO   MdnsClient           MDNS Scan targets updated : commissionable: true
2026-03-28 14:34:14.880 INFO   Controller~ndHandler Controller started
2026-03-28 14:34:14.880 INFO   Controller~ndHandler OTA event handlers registered
2026-03-28 14:34:14.881 INFO   DclVendorInfoService Initialize VendorInfoService source: https://on.dcl.csa-iot.org interval: 24h
2026-03-28 14:34:14.881 INFO   DclCertifi~teService Initialize CertificateService prod: https://on.dcl.csa-iot.org
2026-03-28 14:34:14.884 INFO   DclVendorInfoService Fetching vendor information from DCL
2026-03-28 14:34:14.891 INFO   DclCertifi~teService Loaded 0 certificates from storage
2026-03-28 14:34:15.321 INFO   DclVendorInfoService Fetched 408 vendors from DCL
2026-03-28 14:34:15.325 INFO   DclVendorInfoService Stored 412 vendors
noble warning: adapter does not support Bluetooth Low Energy (BLE, Bluetooth Smart).
               Try to run with environment variable:
               [sudo] NOBLE_HCI_DEVICE_ID=x node ...
2026-03-28 14:34:18.576 INFO   DclCertifi~teService Downloaded and stored 74 new certificates (total: 74)
2026-03-28 14:34:18.576 INFO   Controller~ndHandler Found 0 nodes:
2026-03-28 14:34:18.576 INFO   Controller~ndHandler All 0 nodes initialized, starting connections
2026-03-28 14:34:18.579 INFO   WebServer            Webserver listening on http://0.0.0.0:5580
Stopping webserver...
2026-03-28 14:35:01.547 NOTICE Runtime              Shutting down
2026-03-28 14:35:01.548 ERROR  Runtime              Unhandled error closing worker: Could not start scanning, state is unsupported (not poweredOn)
  at Noble.scan (/app/node_modules/@stoprocent/noble/lib/noble.js:193:23)
  at Noble.startScanning (/app/node_modules/@stoprocent/noble/lib/noble.js:217:12)
  at NobleBleClient.close (/app/node_modules/@matter/nodejs-ble/src/NobleBleClient.ts:155:19)
  at cancel (/app/node_modules/@matter/general/src/environment/RuntimeService.ts:246:51)
  at RuntimeService.#cancelWorker (/app/node_modules/@matter/general/src/environment/RuntimeService.ts:275:16)
  at RuntimeService.cancel (/app/node_modules/@matter/general/src/environment/RuntimeService.ts:166:35)
  at RuntimeService.interrupt (/app/node_modules/@matter/general/src/environment/RuntimeService.ts:179:14)
  at process.interruptHandler (/app/node_modules/@matter/nodejs/src/environment/ProcessManager.ts:110:22)
  at process.emit (node:events:531:35)
2026-03-28 14:35:01.556 NOTICE Node                 server-1-fff1 going offline
Handlers unregistered
Servers closed
2026-03-28 14:35:01.558 INFO   CustomClusterPoller  Custom attribute poller stopped
2026-03-28 14:35:01.565 INFO   MdnsAdvertisement    Unpublishing kind: operational service: mdns:2047FEC6DD3B68FA-000000000001B669._matter._tcp.local time: 46.7s
2026-03-28 14:35:01.566 NOTICE Node                 server-1-fff1 is offline
2026-03-28 14:35:01.571 INFO   ServerNodeStore      Closed server-1-fff1 storage location: /data/server-1-fff1 driver: file

Device Information

No response

Additional Context

No response

Pre-submission Checklist

  • I am running an Alpha/Beta version of the Matter.js server
  • I have included the complete server logs (not truncated)
  • I have checked existing issues to avoid duplicates

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions