{"record":{"id":"2c57f7bbc6331b6a","repo":"homebridge/homebridge","slug":"matter-network-error-error-message","errorCode":null,"errorMessage":"Matter network error: ${error.message}","messagePattern":"Matter network error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/matter/errorHandler.ts","lineNumber":137,"sourceCode":"    }\n\n    // Default to unknown error\n    return new MatterError(\n      error.message || 'Unknown Matter error',\n      'UNKNOWN_ERROR',\n      { recoverable: false, type: MatterErrorType.UNKNOWN, originalError: error },\n    )\n  }\n\n  /**\n   * Log error with appropriate severity and user-friendly messages\n   */\n  private logError(error: MatterError): void {\n    if (error instanceof MatterNetworkError) {\n      if (error.details?.code === 'PORT_IN_USE') {\n        log.error('Matter port is already in use. Please configure a different port in your config.json.')\n      } else {\n        log.warn(`Matter network error: ${error.message}`)\n      }\n    } else if (error instanceof MatterCommissioningError) {\n      log.info(`Matter commissioning issue: ${error.message}`)\n    } else if (error instanceof MatterDeviceError) {\n      log.debug(`Device sync error: ${error.message}`)\n    } else if (error instanceof MatterStorageError) {\n      log.warn(`Matter storage error: ${error.message}`)\n      if (error.message.includes('corrupted')) {\n        log.warn('If this persists, you may need to delete the Matter storage directory and re-pair your devices.')\n      }\n    } else if (error.code === 'CONFIGURATION_ERROR') {\n      log.error(`Matter configuration error: ${error.message}`)\n    } else if (error.code === 'SERVER_ERROR') {\n      log.error(`Matter server error: ${error.message}`)\n    } else {\n      log.error(`Matter error: ${error.message}`)\n    }\n","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/homebridge/homebridge/blob/edf54930340d67cade23d01abd41b03cd9621e8b/src/matter/errorHandler.ts#L119-L155","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read error.message for the specific network failure (EADDRNOTAVAIL, ECONNREFUSED, timeout, etc.).","Allow UDP traffic on the Matter port and mDNS (5353) through the firewall; ensure multicast is enabled on the network.","If running in Docker, use host networking so mDNS advertising works.","Check that the machine's interfaces/IPs are stable (no flapping DHCP) and IPv6 is available."],"exampleFix":"// before (ufw)\nufw status   # blocks udp 5540/5353\n// after\nufw allow 5540/udp\nufw allow 5353/udp","handlingStrategy":"try-catch","validationCode":"// preflight: verify required UDP ports and mDNS availability\nimport { createSocket } from 'node:dgram'\nfunction udpPortFree(port: number): Promise<boolean> {\n  return new Promise(res => {\n    const s = createSocket('udp4')\n    s.once('error', () => res(false)); s.once('listening', () => s.close(() => res(true)))\n    s.bind(port)\n  })\n}","typeGuard":"function isPortInUseError(e: MatterError): e is MatterError & { details?: { code: string } } {\n  return (e as any).details?.code === 'PORT_IN_USE'\n}","tryCatchPattern":"try {\n  await startMatterServer()\n} catch (e) {\n  if (isPortInUseError(e)) {\n    log.error('Pick another matterPort in config.json')\n  } else {\n    log.warn(`Matter network error: ${(e as Error).message}`)\n  }\n}","preventionTips":["Open UDP for the Matter port and 5353 (mDNS) in host and container firewalls","Use host networking in Docker for multicast support","Keep device IPs/DHCP leases stable and IPv6 enabled","Validate the configured Matter port is free before startup"],"tags":["matter","network","udp","mdns"],"backgroundTag":"matter-network-error","analyzedSha":"edf54930340d67cade23d01abd41b03cd9621e8b","analyzedAt":"2026-08-30T21:28:53.235Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}