{"record":{"id":"f7a9dd6496ebf674","repo":"homebridge/homebridge","slug":"updateaccessorystate-cluster-parameter-is-require","errorCode":null,"errorMessage":"updateAccessoryState: cluster parameter is required for accessory ${uuid}","messagePattern":"updateAccessoryState: cluster parameter is required for accessory (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/matter/MatterAPIImpl.ts","lineNumber":461,"sourceCode":"  /**\n   * Update a Matter accessory's cluster state\n   * Validates inputs before updating\n   */\n  async updateAccessoryState(\n    uuid: string,\n    cluster: string,\n    attributes: Record<string, unknown>,\n    partId?: string,\n  ): Promise<void> {\n    // Validate inputs\n    if (!uuid) {\n      log.error('updateAccessoryState: uuid parameter is required')\n      return\n    }\n\n    if (!cluster) {\n      log.error(`updateAccessoryState: cluster parameter is required for accessory ${uuid}`)\n      return\n    }\n\n    if (!attributes || Object.keys(attributes).length === 0) {\n      log.warn(`updateAccessoryState: No attributes provided for accessory ${uuid}, cluster ${cluster}`)\n      return\n    }\n\n    // Validate cluster name (warning only, don't block)\n    this.validateClusterName(cluster, `updateAccessoryState (${uuid})`)\n\n    this.assertMatterReady(`Cannot update Matter accessory ${uuid}`)\n\n    log.debug(\n      `Updating Matter accessory state: uuid=${uuid}, cluster=${cluster}, attributes=${Object.keys(attributes).join(', ')}${partId ? `, partId=${partId}` : ''}`,\n    )\n\n    // Emit the event (listeners will be called synchronously by EventEmitter)\n    this.api.emit(InternalAPIEvent.UPDATE_MATTER_ACCESSORY_STATE, uuid, cluster, attributes, partId)","sourceCodeStart":443,"sourceCodeEnd":479,"githubUrl":"https://github.com/homebridge/homebridge/blob/edf54930340d67cade23d01abd41b03cd9621e8b/src/matter/MatterAPIImpl.ts#L443-L479","documentation":"`api.matter.updateAccessoryState(uuid, cluster, attributes)` validates its arguments and silently logs an error and returns instead of throwing when `cluster` is falsy. The library needs a Matter cluster name (e.g. 'onOff', 'switch', 'levelControl') to route the attribute update to the right cluster server on the accessory. Without it, no state update is emitted and the accessory's HomeKit/Matter view stays stale.","triggerScenarios":"Calling `api.matter.updateAccessoryState(uuid, '', attrs)`, `updateAccessoryState(uuid, undefined as any, attrs)`, or `updateAccessoryState(uuid, null, attrs)` — i.e. the cluster string is missing, empty, or comes from an undefined variable/config field.","commonSituations":"Plugin authors derive the cluster name from a dynamic variable (config key, map lookup) that is undefined; refactors rename a cluster constant; copying sample code and forgetting to fill in the cluster argument; using a variable typed loosely (any) so TypeScript does not catch the empty string.","solutions":["Pass a valid cluster name as the second argument, e.g. `api.matter.updateAccessoryState(uuid, 'onOff', { on: true })`.","Check where the cluster value originates (config field, lookup map) and ensure it is defined before calling.","Use the exported cluster-name constants/helpers from the plugin API surface instead of hand-written strings so typos/undefined values are caught at compile time.","Note the method returns silently — check the Homebridge log for 'updateAccessoryState: cluster parameter is required' to confirm the call was dropped."],"exampleFix":"// before\nconst cluster = config.cluster // undefined if not configured\nawait api.matter.updateAccessoryState(accessory.UUID, cluster, { on: true })\n// after\nconst cluster = config.cluster ?? 'onOff'\nif (!cluster) throw new Error('cluster must be configured')\nawait api.matter.updateAccessoryState(accessory.UUID, cluster, { on: true })","handlingStrategy":"validation","validationCode":"if (!cluster || typeof cluster !== 'string') {\n  throw new Error(`cluster must be a non-empty string, got: ${cluster}`)\n}\nawait api.matter.updateAccessoryState(uuid, cluster, attributes)","typeGuard":"function isValidCluster(c: unknown): c is string {\n  return typeof c === 'string' && c.length > 0\n}","tryCatchPattern":null,"preventionTips":["Use exported cluster-name constants instead of raw strings","Type the cluster field in plugin config schemas as required","Check the Homebridge log after state updates during development"],"tags":["matter","api-usage","missing-argument","silent-failure"],"backgroundTag":"missing-required-argument","analyzedSha":"edf54930340d67cade23d01abd41b03cd9621e8b","analyzedAt":"2026-08-30T21:28:53.235Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}