{"record":{"id":"2cca87bf53afeacc","repo":"ruvnet/ruflo","slug":"pairing-failed-for-device-device-deviceid","errorCode":null,"errorMessage":"Pairing failed for device ${device.deviceId}","messagePattern":"Pairing failed for device (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugin-iot-cognitum/src/domain/services/device-lifecycle-service.ts","lineNumber":116,"sourceCode":"      endpoint,\n      metadata: {},\n    };\n\n    this.deps.onDeviceRegistered?.(device);\n    return device;\n  }\n\n  /**\n   * Pair a device using the SDK's pair.create() and promote its trust level.\n   */\n  async pairDevice(\n    device: DeviceAgent,\n    clientName: string,\n  ): Promise<DeviceAgent> {\n    const result = await this.deps.pairDevice(device.deviceId, clientName);\n\n    if (!result.paired) {\n      throw new Error(`Pairing failed for device ${device.deviceId}`);\n    }\n\n    const oldLevel = device.trustLevel;\n    const newLevel =\n      device.trustLevel < DeviceTrustLevel.PROVISIONED\n        ? DeviceTrustLevel.PROVISIONED\n        : device.trustLevel;\n\n    const updated: DeviceAgent = {\n      ...device,\n      trustLevel: newLevel,\n      trustScore: {\n        ...device.trustScore,\n        overall: this.computeTrustScore(device, 0, 0, true).overall,\n        components: {\n          ...device.trustScore.components,\n          pairingIntegrity: 1.0,\n        },","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugin-iot-cognitum/src/domain/services/device-lifecycle-service.ts#L98-L134","documentation":"DeviceLifecycleService.pairDevice calls the device SDK's pair.create() and expects result.paired === true; a structured false result is converted into this exception. It indicates the pairing protocol ran but the device did not confirm pairing — distinct from transport errors, which the SDK would raise itself.","triggerScenarios":"Pairing a device that is offline or at the wrong endpoint; the device's pairing window or confirmation step expired; trust/credential mismatch between coordinator and Seed device; SDK returning paired:false for a busy device.","commonSituations":"Provisioning lines where the device was power-cycled mid-flow; long delays between initiating and confirming pairing; retrying pairing after a partially completed earlier attempt.","solutions":["Verify the device is powered, online, and in pairing mode, then restart the pair flow from the beginning","Check the SDK logs or device endpoint for the underlying refusal reason (timeout, confirmation mismatch)","If an earlier partial pairing left state behind, reset or unregister the device and re-pair"],"exampleFix":"// before\nconst updated = await lifecycle.pairDevice(device, 'gateway-1'); // paired=false -> throws\n\n// after\nconst probe = await sdkPair(device.deviceId, 'gateway-1');\nif (!probe.paired) {\n  logger.warn(`pair refused for ${device.deviceId}; keeping trust level ${device.trustLevel}`);\n} else {\n  const updated = await lifecycle.pairDevice(device, 'gateway-1');\n}","handlingStrategy":"try-catch","validationCode":"const reachable = await pingDevice(device.endpoint);\nif (!reachable) {\n  throw new Error(`device ${device.deviceId} unreachable; skip pairing attempt`);\n}\nreturn lifecycle.pairDevice(device, clientName);","typeGuard":null,"tryCatchPattern":"for (let attempt = 1; attempt <= 3; attempt++) {\n  try {\n    return await lifecycle.pairDevice(device, clientName);\n  } catch (e) {\n    if (e instanceof Error && e.message.startsWith('Pairing failed for device ')) {\n      await sleep(backoff(attempt)); // device may still be in pairing mode\n      continue;\n    }\n    throw e;\n  }\n}\nthrow new Error('pairing retries exhausted');","preventionTips":["Confirm the device is powered, online, and in pairing mode before invoking pairDevice","Restart the full pairing flow on refusal instead of half-promoting trust","Log the SDK pair result reason to distinguish refusals from crashes"],"tags":["iot","device-pairing","provisioning","trust"],"backgroundTag":"device-pairing-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}