{"record":{"id":"1cf122728cc36c15","repo":"homebridge/homebridge","slug":"matter-accessory-accessory-displayname-is-mis","errorCode":null,"errorMessage":"Matter accessory \"${accessory.displayName}\" is missing required field 'serialNumber'.\nExample: serialNumber: 'ABC123' or serialNumber: accessory.UUID","messagePattern":"Matter accessory \"(.+?)\" is missing required field 'serialNumber'\\.\nExample: serialNumber: 'ABC123' or serialNumber: accessory\\.UUID","errorType":"validation","errorClass":"MatterDeviceError","httpStatus":null,"severity":"error","filePath":"src/matter/serverHelpers.ts","lineNumber":97,"sourceCode":"  }\n\n  if (!accessory.UUID) {\n    throw new MatterDeviceError(\n      'Matter accessory is missing required field \\'UUID\\'.\\n'\n      + 'Generate a unique UUID for your accessory:\\n'\n      + '  const UUID = api.hap.uuid.generate(\\'my-unique-id\\')',\n    )\n  }\n\n  if (!accessory.displayName) {\n    throw new MatterDeviceError(\n      `Matter accessory (${accessory.UUID}) is missing required field 'displayName'.\\n`\n      + 'Example: displayName: \\'Living Room Light\\'',\n    )\n  }\n\n  if (!accessory.serialNumber) {\n    throw new MatterDeviceError(\n      `Matter accessory \"${accessory.displayName}\" is missing required field 'serialNumber'.\\n`\n      + 'Example: serialNumber: \\'ABC123\\' or serialNumber: accessory.UUID',\n    )\n  }\n\n  if (!accessory.manufacturer) {\n    throw new MatterDeviceError(\n      `Matter accessory \"${accessory.displayName}\" is missing required field 'manufacturer'.\\n`\n      + 'Example: manufacturer: \\'Homebridge\\' or manufacturer: \\'My Plugin Name\\'',\n    )\n  }\n\n  if (!accessory.model) {\n    throw new MatterDeviceError(\n      `Matter accessory \"${accessory.displayName}\" is missing required field 'model'.\\n`\n      + 'Example: model: \\'v1.0\\' or model: \\'Smart Light\\'',\n    )\n  }","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/homebridge/homebridge/blob/edf54930340d67cade23d01abd41b03cd9621e8b/src/matter/serverHelpers.ts#L79-L115","documentation":"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.","triggerScenarios":"registerAccessory is called with an accessory that has UUID, displayName, deviceType, but no serialNumber property.","commonSituations":"Ported HAP plugins where serial number was optional; generated accessories where the vendor serial is unavailable; developers unaware Matter requires it.","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"],"exampleFix":"// before\n{ UUID, displayName: 'Light', deviceType, manufacturer: 'Acme' }\n// after\n{ UUID, displayName: 'Light', deviceType, manufacturer: 'Acme', serialNumber: UUID }","handlingStrategy":"validation","validationCode":"if (!accessory.serialNumber) accessory.serialNumber = accessory.UUID","typeGuard":"function hasSerialNumber(a: Partial<MatterAccessory>): a is MatterAccessory {\n  return typeof a.serialNumber === 'string' && a.serialNumber.length > 0\n}","tryCatchPattern":"try {\n  api.matter!.registerAccessory(pluginName, accessory)\n} catch (e) {\n  if (String(e).includes(\"missing required field 'serialNumber'\")) log.error('set serialNumber (accessory.UUID is a fine default)')\n  throw e\n}","preventionTips":["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"],"tags":["matter","validation","plugin-api"],"backgroundTag":"missing-required-field","analyzedSha":"edf54930340d67cade23d01abd41b03cd9621e8b","analyzedAt":"2026-08-30T21:28:53.235Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}