{"record":{"id":"f9a9c0a0b82d94df","repo":"jumpserver/jumpserver","slug":"generate-random-error-f9a9c0","errorCode":null,"errorMessage":"generate random error","messagePattern":"generate random error","errorType":"exception","errorClass":"GMDeviceError","httpStatus":null,"severity":"critical","filePath":"apps/common/sdk/gm/sctu/session.py","lineNumber":20,"sourceCode":"\nfrom common.sdk.gm.base.exception import GMDeviceError\nfrom .session_mixin import SM4Mixin\n\n\nclass Session(SM4Mixin):\n    def __init__(self, driver, session):\n        super().__init__()\n        self._session = session\n        self._driver = driver\n\n    def get_device_info(self):\n        pass\n\n    def generate_random(self, length=64):\n        random_data = (c_ubyte * length)()\n        ret = self._driver.HS_SDF_GenerateRandom(self._session, c_int(length), random_data)\n        if ret != 0:\n            raise GMDeviceError(\"generate random error\", ret)\n        return bytes(random_data)\n\n    def close(self):\n        ret = self._driver.HS_SDF_CloseSession(self._session)\n        if ret != 0:\n            raise GMDeviceError(\"close session failed\", ret)\n","sourceCodeStart":2,"sourceCodeEnd":27,"githubUrl":"https://github.com/jumpserver/jumpserver/blob/6ec464fabd61b95912d539455a3a5f15f5c59fe0/apps/common/sdk/gm/sctu/session.py#L2-L27","documentation":"Raised by GM/SM crypto HSM session wrapper when the underlying HS_SDF_GenerateRandom driver call returns a non-zero return code. It means the hardware security device (SDF-compatible GM card) failed to produce the requested random bytes. The numeric code carried in the exception indicates the device-level reason.","triggerScenarios":"Calling session.generate_random(length) while the HSM device is malfunctioning, disconnected, out of entropy, or when the session handle is stale/invalid after a device restart. Also triggered if length is invalid for the device.","commonSituations":"HSM USB/PCIe link dropped, device driver crashed or was reloaded, session opened before device firmware finished initializing, entropy pool exhausted on virtual/emulated SDF devices, or a stale session handle after the daemon restarted.","solutions":["Check the numeric ret code against the SDF/GM error code table to identify the device reason","Verify the device is present and the driver daemon is running, then reopen the session and retry","Open a fresh session (device.open_session()) if the old handle went stale after device restart","Inspect device logs / contact vendor if the code persists on a healthy-looking device"],"exampleFix":"// before\nrnd = session.generate_random(64)\n\n// after\ntry:\n    rnd = session.generate_random(64)\nexcept GMDeviceError as e:\n    logger.error(f\"HSM random failed: code={e.args[1:]}\")\n    session = device.open_session()  # reopen and retry once\n    rnd = session.generate_random(64)","handlingStrategy":"retry","validationCode":"# probe the device before relying on it\nret = device.open_session()  # raises early if device unhealthy\nsession = ret","typeGuard":null,"tryCatchPattern":"try:\n    rnd = session.generate_random(64)\nexcept GMDeviceError as e:\n    logger.error(f\"HSM random failed: {e}\")\n    session = device.open_session()\n    rnd = session.generate_random(64)  # one retry with fresh session","preventionTips":["Keep a health-check on the HSM session in long-running services","Reopen sessions on a schedule or after any GMDeviceError","Monitor the device daemon and alert on restarts"],"tags":["gm","hsm","crypto","random","hardware"],"backgroundTag":"hardware-security-module-error","analyzedSha":"6ec464fabd61b95912d539455a3a5f15f5c59fe0","analyzedAt":"2026-08-28T11:33:00.925Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}