{"record":{"id":"2dd372f927fcab56","repo":"homebridge/homebridge","slug":"failed-to-identify-message","errorCode":null,"errorMessage":"Failed to identify: ${message}","messagePattern":"Failed to identify: (.+?)","errorType":"exception","errorClass":"StatusResponseError","httpStatus":null,"severity":"error","filePath":"src/matter/behaviors/IdentifyBehavior.ts","lineNumber":46,"sourceCode":"    const registry = this.getRegistry()\n\n    try {\n      // Execute user handler\n      await registry.executeHandler(endpointId, 'identify', 'identify', request)\n\n      // Only reached if handler succeeded - call base implementation\n      return await super.identify(request)\n    } catch (error) {\n      // If user handler already threw a StatusResponseError, propagate it as-is\n      // This sends a proper Matter protocol error response to the controller\n      if (MatterStatus.isMatterProtocolError(error)) {\n        throw error\n      }\n\n      // For other errors, wrap in appropriate StatusResponseError\n      // This prevents the endpoint from crashing and keeps the device online\n      const message = error instanceof Error ? error.message : String(error)\n      throw new StatusResponseError(`Failed to identify: ${message}`, Status.Failure)\n    }\n  }\n}\n","sourceCodeStart":28,"sourceCodeEnd":50,"githubUrl":"https://github.com/homebridge/homebridge/blob/edf54930340d67cade23d01abd41b03cd9621e8b/src/matter/behaviors/IdentifyBehavior.ts#L28-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped message after 'Failed to identify: ' to find the real error from your plugin's identify handler.","Make the identify handler defensive: wrap device I/O in try/catch so identification never hard-fails (identify is cosmetic).","Throw StatusResponseError from the handler if you want a specific Matter status surfaced to the controller.","Verify the target device is reachable and credentials are valid, then re-run identify from the controller.","Add a regression test that calls the registered identify handler with the device offline."],"exampleFix":"// before\nasync identify() {\n  await this.device.blink() // throws when device offline\n}\n\n// after\nasync identify() {\n  try {\n    await this.device.blink()\n  } catch (e) {\n    this.log.warn('identify blink failed: %s', e) // identify is best-effort\n  }\n}","handlingStrategy":"try-catch","validationCode":"// Plugin-side guard inside identify():\nif (!this.device) throw new StatusResponseError('Accessory device not initialized', Status.Failure)","typeGuard":"const isMatterError = (e: unknown): e is StatusResponseError => e instanceof StatusResponseError","tryCatchPattern":"try {\n  await controller.triggerIdentify(accessoryId)\n} catch (e) {\n  if (e instanceof StatusResponseError && e.message.startsWith('Failed to identify: ')) {\n    log.warn('identify failed, cause: %s', e.message.slice('Failed to identify: '.length))\n  }\n}","preventionTips":["Treat identify as best-effort: catch and log failures inside the plugin's identify handler instead of throwing.","Never perform mandatory network I/O in identify; keep it to a quick, optional visual effect.","Test identify with the device offline before publishing the plugin.","Ensure the handler never throws non-Error values (strings) - always throw Error or StatusResponseError.","Initialize device references before registration so identify cannot hit undefined state."],"tags":["matter","identify","plugin-handler","status-response-error"],"backgroundTag":"matter-command-handler-failed","analyzedSha":"edf54930340d67cade23d01abd41b03cd9621e8b","analyzedAt":"2026-08-30T21:28:53.235Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}