homebridge/homebridge · error · MatterDeviceError

Matter configuration validation failed: ${errors.map(e => `

Error message

Matter configuration validation failed:
${errors.map(e => `  - ${e}`).join('
')}

What it means

ServerConfig.validateAndSanitizeConfig collects validation errors for the Matter server configuration (port, vendor/product ids, etc.) and throws a single aggregated MatterDeviceError listing every offending field when any are invalid. It runs when constructing the Matter server config.

Source

Thrown at src/matter/server/ServerConfig.ts:96

  if (firmwareRevision !== undefined) {
    firmwareRevision = truncateString(firmwareRevision, 64, 'Firmware revision').value
  }

  // Validate serialNumber
  let serialNumber = config.serialNumber
  if (serialNumber !== undefined) {
    serialNumber = truncateString(serialNumber, 32, 'Serial number').value
  }

  // Validate debugModeEnabled
  const debugModeEnabled = config.debugModeEnabled || false

  // Validate externalAccessory
  const externalAccessory = config.externalAccessory || false

  // Throw if there are validation errors
  if (errors.length > 0) {
    throw new MatterDeviceError(
      `Matter configuration validation failed:\n${errors.map(e => `  - ${e}`).join('\n')}`,
    )
  }

  return {
    port,
    uniqueId,
    storagePath,
    displayName: config.displayName,
    manufacturer,
    model,
    firmwareRevision,
    serialNumber,
    debugModeEnabled,
    externalAccessory,
    networkInterfaces: config.networkInterfaces,
    disableIpv4: config.disableIpv4,
    deferOnline: config.deferOnline,

View on GitHub (pinned to edf5493034)

Solutions

1. Read the bullet list in the error message — each line names one invalid field
2. Fix the matter block in config.json (valid port 1–65535, valid vendorId/productId)
3. Remove conflicting or unknown fields from the matter config
4. Restart homebridge after editing config

Example fix

// before
"matter": { "port": "5540", "vendorId": 65535 }
// after
"matter": { "port": 5540, "vendorId": 65521, "productId": 32768 }

const port = Number(cfg.matter.port)
if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('invalid matter port')
if (cfg.matter.vendorId != null && (cfg.matter.vendorId < 1 || cfg.matter.vendorId > 65535)) throw new Error('invalid vendorId')

try { await server.start() } catch (e) { if ((e as Error).message.startsWith('Matter configuration validation failed')) { console.error(e.message); process.exit(1) } throw e }

When it happens

Trigger: Config with an invalid or out-of-range port, missing/invalid vendorId or productId, invalid externalAccessory value, or other schema violations in the bridge.matter block.

Common situations: Hand-edited config.json with a string port or port 0, vendorId/productId outside 0x0001–0xFFF0, or a child bridge _block copied incorrectly.

Related errors

• Storage path is required for Matter server
• Matter accessory "${accessory.displayName}" part "${part.id}
• Matter accessory "${accessory.displayName}" part "${part.id}
• ${context}: Matter accessory missing required 'UUID' field
• ${context}: Matter accessory '${accessory.UUID}' missing req

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