homebridge/homebridge · error

updateAccessoryState: cluster parameter is required for acce

Error message

updateAccessoryState: cluster parameter is required for accessory ${uuid}

What it means

`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.

Source

Thrown at src/matter/MatterAPIImpl.ts:461

  /**
   * Update a Matter accessory's cluster state
   * Validates inputs before updating
   */
  async updateAccessoryState(
    uuid: string,
    cluster: string,
    attributes: Record<string, unknown>,
    partId?: string,
  ): Promise<void> {
    // Validate inputs
    if (!uuid) {
      log.error('updateAccessoryState: uuid parameter is required')
      return
    }

    if (!cluster) {
      log.error(`updateAccessoryState: cluster parameter is required for accessory ${uuid}`)
      return
    }

    if (!attributes || Object.keys(attributes).length === 0) {
      log.warn(`updateAccessoryState: No attributes provided for accessory ${uuid}, cluster ${cluster}`)
      return
    }

    // Validate cluster name (warning only, don't block)
    this.validateClusterName(cluster, `updateAccessoryState (${uuid})`)

    this.assertMatterReady(`Cannot update Matter accessory ${uuid}`)

    log.debug(
      `Updating Matter accessory state: uuid=${uuid}, cluster=${cluster}, attributes=${Object.keys(attributes).join(', ')}${partId ? `, partId=${partId}` : ''}`,
    )

    // Emit the event (listeners will be called synchronously by EventEmitter)
    this.api.emit(InternalAPIEvent.UPDATE_MATTER_ACCESSORY_STATE, uuid, cluster, attributes, partId)

View on GitHub (pinned to edf5493034)

Solutions

1. Pass a valid cluster name as the second argument, e.g. `api.matter.updateAccessoryState(uuid, 'onOff', { on: true })`.
2. Check where the cluster value originates (config field, lookup map) and ensure it is defined before calling.
3. 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.
4. Note the method returns silently — check the Homebridge log for 'updateAccessoryState: cluster parameter is required' to confirm the call was dropped.

Example fix

// before
const cluster = config.cluster // undefined if not configured
await api.matter.updateAccessoryState(accessory.UUID, cluster, { on: true })
// after
const cluster = config.cluster ?? 'onOff'
if (!cluster) throw new Error('cluster must be configured')
await api.matter.updateAccessoryState(accessory.UUID, cluster, { on: true })

if (!cluster || typeof cluster !== 'string') {
  throw new Error(`cluster must be a non-empty string, got: ${cluster}`)
}
await api.matter.updateAccessoryState(uuid, cluster, attributes)

function isValidCluster(c: unknown): c is string {
  return typeof c === 'string' && c.length > 0
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• updateAccessoryState: No attributes provided for accessory $
• External Matter accessory ${accessory.displayName} (${access
• switch.emit: invalid action "${action as string}" — must be
• switch.emit: invalid position ${rawPosition} — must be a fin
• Failed to allocate Matter port for child bridge. Please spec

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