Using IPv6 address in port configuration prevents zigbee-herdsman from starting

[spike77453]

When using an IPv6 address (ULA or GUA), zigbee-herdsman fails with error "No such file or directory...":

Starting Zigbee2MQTT without watchdog.
[2025-12-18 16:58:18] info:         z2m: Logging to console, file (filename: log.log)
[2025-12-18 16:58:18] info:         z2m: Starting Zigbee2MQTT version 2.7.1 (commit #unknown)
[2025-12-18 16:58:18] info:         z2m: Starting zigbee-herdsman (7.0.4)
[2025-12-18 16:58:18] info:         zh:zstack:znp: Opening SerialPort with {"path":"tcp://[fd73:5e46:b9f0:0:80b5:4eff:dead:beef]:6638","baudRate":115200,"rtscts":false,"autoOpen":false}
[2025-12-18 16:58:18] error:         z2m: Error while starting zigbee-herdsman
[2025-12-18 16:58:18] error:         z2m: Failed to start zigbee-herdsman
[2025-12-18 16:58:18] error:         z2m: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start_crashes-runtime.html for possible solutions
[2025-12-18 16:58:18] error:         z2m: Exiting...
[2025-12-18 16:58:18] error:         z2m: Error: Error: No such file or directory, cannot open tcp://[fd73:5e46:b9f0:0:80b5:4eff:dead:beef]:6638

The configuration file looks like this:

$ grep serial -A 2 configuration.yaml 
serial:
  port: tcp://[fd73:5e46:b9f0:0:80b5:4eff:dead:beef]:6638
  adapter: zstack

Note: This does not seem to be an IPv6 issue. The socket can be opened successfully when using a hostname with a AAAA resource record.

After creating a corresponding entry in /etc/hosts (or ensuring there's a corresponding AAAA record on the DNS server) and changing the configuration accordingly

$ echo "fd73:5e46:b9f0:0:80b5:4eff:dead:beef foo" >> /etc/hosts
$ sed -i 's|\(port: tcp://\)\(.*\)|\1foo:6638|g' configuration.yaml 
$ grep serial -A 2 configuration.yaml 
serial:
  port: tcp://foo:6638
  adapter: zstack

zigbee-herdsman starts up just fine:

Starting Zigbee2MQTT without watchdog.
[2025-12-18 17:13:14] info:         z2m: Logging to console, file (filename: log.log)
[2025-12-18 17:13:14] info:         z2m: Starting Zigbee2MQTT version 2.7.1 (commit #unknown)
[2025-12-18 17:13:14] info:         z2m: Starting zigbee-herdsman (7.0.4)
[2025-12-18 17:13:14] info:         zh:zstack:znp: Opening TCP socket with foo:6638
[2025-12-18 17:13:14] info:         zh:zstack:znp: Socket connected
[2025-12-18 17:13:14] info:         zh:zstack:znp: Socket ready
[2025-12-18 17:13:14] info:         zh:zstack:znp: Writing CC2530/CC2531 skip bootloader payload
[2025-12-18 17:13:15] info:         zh:zstack:znp: Skip bootloader for CC2652/CC1352
[2025-12-18 17:13:16] info:         z2m: zigbee-herdsman started (resumed)
...

[Nerivec]

It would fail the regex test, so would fallback to trying the path as serial.
Also, not sure the underlying logic would support this, at least in current state (not sure how NodeJS sockets expect ipv6 format).

[spike77453]

NodeJS should have full RFC2732 support, i.e. putting fd73:5e46:b9f0:0:80b5:4eff:dead:beef (without the square brackets) here

zigbee-herdsman/src/adapter/z-stack/znp/znp.ts

Line 165 in 1a640d1

this.socketPort!.connect(info.port, info.host);

should work just fine.

If you stick tcp://[fd73:5e46:b9f0:0:80b5:4eff:dead:beef]:6638 into

zigbee-herdsman/src/adapter/utils.ts

Lines 11 to 19 in 1a640d1

	export function parseTcpPath(path: string): {host: string; port: number} {
	// built-in extra validation
	const info = new URL(path);
	return {
	host: info.hostname,
	port: Number(info.port),
	};
	}

info.hostname will contain the square brackets though, i.e. [fd73:5e46:b9f0:0:80b5:4eff:dead:beef].

So the regex here

zigbee-herdsman/src/adapter/utils.ts

Lines 4 to 9 in 1a640d1

	export function isTcpPath(path: string): boolean {
	// tcp path must be:
	// tcp://<host>:<port>
	const regex = /^(?:tcp:\/\/)[\w.-]+[:][\d]+$/gm;
	return regex.test(path);
	}

needs to be amended (or maybe an additional isTcp6Path is a reasonable idea) and the square brackets need to be stripped from the hostname before handing it to the socket here

zigbee-herdsman/src/adapter/z-stack/znp/znp.ts

Line 165 in 1a640d1

this.socketPort!.connect(info.port, info.host);

That should be it. Hope that helps.