homebridge/homebridge · error · StatusResponseError

Failed to identify: ${message}

Error message

Failed to identify: ${message}

What it means

Thrown by the Identify behavior's public identify() command when the plugin's registered identify handler throws an unexpected error. Homebridge wraps the underlying error into a StatusResponseError with Status.Failure so the Matter controller gets a clean protocol failure and the endpoint stays online. The original error text follows 'Failed to identify: ' in the response/log.

Source

Thrown at src/matter/behaviors/IdentifyBehavior.ts:46

    const registry = this.getRegistry()

    try {
      // Execute user handler
      await registry.executeHandler(endpointId, 'identify', 'identify', request)

      // Only reached if handler succeeded - call base implementation
      return await super.identify(request)
    } catch (error) {
      // If user handler already threw a StatusResponseError, propagate it as-is
      // This sends a proper Matter protocol error response to the controller
      if (MatterStatus.isMatterProtocolError(error)) {
        throw error
      }

      // For other errors, wrap in appropriate StatusResponseError
      // This prevents the endpoint from crashing and keeps the device online
      const message = error instanceof Error ? error.message : String(error)
      throw new StatusResponseError(`Failed to identify: ${message}`, Status.Failure)
    }
  }
}

View on GitHub (pinned to edf5493034)

Solutions

1. Inspect the wrapped message after 'Failed to identify: ' to find the real error from your plugin's identify handler.
2. Make the identify handler defensive: wrap device I/O in try/catch so identification never hard-fails (identify is cosmetic).
3. Throw StatusResponseError from the handler if you want a specific Matter status surfaced to the controller.
4. Verify the target device is reachable and credentials are valid, then re-run identify from the controller.
5. Add a regression test that calls the registered identify handler with the device offline.

Example fix

// before
async identify() {
  await this.device.blink() // throws when device offline
}

// after
async identify() {
  try {
    await this.device.blink()
  } catch (e) {
    this.log.warn('identify blink failed: %s', e) // identify is best-effort
  }
}

// Plugin-side guard inside identify():
if (!this.device) throw new StatusResponseError('Accessory device not initialized', Status.Failure)

const isMatterError = (e: unknown): e is StatusResponseError => e instanceof StatusResponseError

try {
  await controller.triggerIdentify(accessoryId)
} catch (e) {
  if (e instanceof StatusResponseError && e.message.startsWith('Failed to identify: ')) {
    log.warn('identify failed, cause: %s', e.message.slice('Failed to identify: '.length))
  }
}

When it happens

Trigger: A controller triggers the identify command (e.g. 'blink' in Apple Home accessory setup, or Identify cluster IdentifyTime writes); the plugin's identify callback throws or rejects with a non-Matter error. Pre-existing StatusResponseError/Matter protocol errors bypass this wrapper.

Common situations: Identify handler flashes a light via the device cloud API and that call fails during HomeKit pairing; handler references this.config fields that are missing; plugin author throws a plain string; network drop while the user is adding the accessory to Home.

Related errors

• Failed to stop closure: ${message}
• Failed to set color temperature: ${message}
• Failed to set hue and saturation: ${message}
• Failed to set XY color: ${message}
• Failed to set hue: ${message}

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