homebridge/homebridge · error · MatterDeviceError

Matter accessory "${accessory.displayName}" is missing requi

Error message

Matter accessory "${accessory.displayName}" is missing required field 'serialNumber'.
Example: serialNumber: 'ABC123' or serialNumber: accessory.UUID

What it means

serialNumber is a required Matter accessory field used to build the BasicInformation cluster (serial number attribute) which controllers expect. validateAccessoryRequiredFields() throws MatterDeviceError naming the accessory when serialNumber is absent at registration.

Source

Thrown at src/matter/serverHelpers.ts:97

  }

  if (!accessory.UUID) {
    throw new MatterDeviceError(
      'Matter accessory is missing required field \'UUID\'.\n'
      + 'Generate a unique UUID for your accessory:\n'
      + '  const UUID = api.hap.uuid.generate(\'my-unique-id\')',
    )
  }

  if (!accessory.displayName) {
    throw new MatterDeviceError(
      `Matter accessory (${accessory.UUID}) is missing required field 'displayName'.\n`
      + 'Example: displayName: \'Living Room Light\'',
    )
  }

  if (!accessory.serialNumber) {
    throw new MatterDeviceError(
      `Matter accessory "${accessory.displayName}" is missing required field 'serialNumber'.\n`
      + 'Example: serialNumber: \'ABC123\' or serialNumber: accessory.UUID',
    )
  }

  if (!accessory.manufacturer) {
    throw new MatterDeviceError(
      `Matter accessory "${accessory.displayName}" is missing required field 'manufacturer'.\n`
      + 'Example: manufacturer: \'Homebridge\' or manufacturer: \'My Plugin Name\'',
    )
  }

  if (!accessory.model) {
    throw new MatterDeviceError(
      `Matter accessory "${accessory.displayName}" is missing required field 'model'.\n`
      + 'Example: model: \'v1.0\' or model: \'Smart Light\'',
    )
  }

View on GitHub (pinned to edf5493034)

Solutions

Set accessory.serialNumber, e.g. serialNumber: accessory.UUID or a stable vendor serial
Derive a deterministic pseudo-serial from the uuid if no hardware serial exists
Ensure serialNumber is a string, not a number

Example fix

// before
{ UUID, displayName: 'Light', deviceType, manufacturer: 'Acme' }
// after
{ UUID, displayName: 'Light', deviceType, manufacturer: 'Acme', serialNumber: UUID }

Defensive patterns

Strategy: validation

Validate before calling

if (!accessory.serialNumber) accessory.serialNumber = accessory.UUID

Type guard

function hasSerialNumber(a: Partial<MatterAccessory>): a is MatterAccessory {
  return typeof a.serialNumber === 'string' && a.serialNumber.length > 0
}

Try / catch

try {
  api.matter!.registerAccessory(pluginName, accessory)
} catch (e) {
  if (String(e).includes("missing required field 'serialNumber'")) log.error('set serialNumber (accessory.UUID is a fine default)')
  throw e
}

Prevention

Fall back to accessory.UUID when no hardware serial exists
Keep serialNumber a stable string across restarts
Add a shared factory that fills serialNumber, manufacturer, model together
Verify all BasicInformation fields in one pre-registration check

When it happens

Trigger: registerAccessory is called with an accessory that has UUID, displayName, deviceType, but no serialNumber property.

Common situations: Ported HAP plugins where serial number was optional; generated accessories where the vendor serial is unavailable; developers unaware Matter requires it.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

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