homebridge/homebridge · warning

Matter network error: ${error.message}

Error message

Matter network error: ${error.message}

What it means

A MatterError classified as MatterNetworkError was handled by errorHandler.handleError -> logError. Special-cased PORT_IN_USE gets its own message; all other network errors are logged as warnings with the raw error text. It signals transport/network-level trouble between the Matter server and controllers.

Source

Thrown at src/matter/errorHandler.ts:137

    }

    // Default to unknown error
    return new MatterError(
      error.message || 'Unknown Matter error',
      'UNKNOWN_ERROR',
      { recoverable: false, type: MatterErrorType.UNKNOWN, originalError: error },
    )
  }

  /**
   * Log error with appropriate severity and user-friendly messages
   */
  private logError(error: MatterError): void {
    if (error instanceof MatterNetworkError) {
      if (error.details?.code === 'PORT_IN_USE') {
        log.error('Matter port is already in use. Please configure a different port in your config.json.')
      } else {
        log.warn(`Matter network error: ${error.message}`)
      }
    } else if (error instanceof MatterCommissioningError) {
      log.info(`Matter commissioning issue: ${error.message}`)
    } else if (error instanceof MatterDeviceError) {
      log.debug(`Device sync error: ${error.message}`)
    } else if (error instanceof MatterStorageError) {
      log.warn(`Matter storage error: ${error.message}`)
      if (error.message.includes('corrupted')) {
        log.warn('If this persists, you may need to delete the Matter storage directory and re-pair your devices.')
      }
    } else if (error.code === 'CONFIGURATION_ERROR') {
      log.error(`Matter configuration error: ${error.message}`)
    } else if (error.code === 'SERVER_ERROR') {
      log.error(`Matter server error: ${error.message}`)
    } else {
      log.error(`Matter error: ${error.message}`)
    }

View on GitHub (pinned to edf5493034)

Solutions

1. Read error.message for the specific network failure (EADDRNOTAVAIL, ECONNREFUSED, timeout, etc.).
2. Allow UDP traffic on the Matter port and mDNS (5353) through the firewall; ensure multicast is enabled on the network.
3. If running in Docker, use host networking so mDNS advertising works.
4. Check that the machine's interfaces/IPs are stable (no flapping DHCP) and IPv6 is available.

Example fix

// before (ufw)
ufw status   # blocks udp 5540/5353
// after
ufw allow 5540/udp
ufw allow 5353/udp

// preflight: verify required UDP ports and mDNS availability
import { createSocket } from 'node:dgram'
function udpPortFree(port: number): Promise<boolean> {
  return new Promise(res => {
    const s = createSocket('udp4')
    s.once('error', () => res(false)); s.once('listening', () => s.close(() => res(true)))
    s.bind(port)
  })
}

function isPortInUseError(e: MatterError): e is MatterError & { details?: { code: string } } {
  return (e as any).details?.code === 'PORT_IN_USE'
}

try {
  await startMatterServer()
} catch (e) {
  if (isPortInUseError(e)) {
    log.error('Pick another matterPort in config.json')
  } else {
    log.warn(`Matter network error: ${(e as Error).message}`)
  }
}

When it happens

Trigger: Any matter.js operation that rejects with MatterNetworkError (not PORT_IN_USE): UDP socket failures, network unreachable, invalid peer addresses, or MDNS/discovery network issues.

Common situations: Port conflicts caught by a different code path, firewall blocking UDP 5353 (mDNS) or the Matter port, Docker/network namespace isolation, IPv6 disabled where required, or controllers on a different VLAN.

Related errors

• bridge.bind is not set. Matter mDNS will listen on all netwo
• Failed to allocate Matter port for child bridge. Please spec
• PORT_IN_USE
• CONNECTION_FAILED
• Matter port range ${rangeStart}-${rangeEnd} exhausted, alloc

AI-assisted analysis of homebridge/homebridge@edf5493034 (2026-08-30). Data as JSON: /api/errors/2c57f7bbc6331b6a. Report an issue: GitHub.