{"record":{"id":"e64aec6bea043fce","repo":"iflytek/astron-agent","slug":"acquire-timeout","errorCode":"ACQUIRE_TIMEOUT","errorMessage":"Distributed lock acquisition timeout","messagePattern":"Distributed lock acquisition timeout","errorType":"exception","errorClass":"DistributedLockException","httpStatus":null,"severity":"warning","filePath":"console/backend/hub/src/main/java/com/iflytek/astron/console/hub/aspect/DistributedLockAspect.java","lineNumber":226,"sourceCode":"    /**\n     * Handle lock acquisition failure\n     */\n    private Object handleLockFailure(String lockKey, DistributedLock distributedLock,\n            ProceedingJoinPoint point) throws Throwable {\n        logLockFailure(lockKey, distributedLock);\n        return executeFailureStrategy(lockKey, distributedLock, point);\n    }\n\n    private void logLockFailure(String lockKey, DistributedLock distributedLock) {\n        String message = String.format(\"Failed to acquire distributed lock: key=%s, waitTime=%d%s\",\n                lockKey, distributedLock.waitTime(), distributedLock.timeUnit().name().toLowerCase());\n        log.warn(message);\n    }\n\n    private Object executeFailureStrategy(String lockKey, DistributedLock distributedLock,\n                                        ProceedingJoinPoint point) throws Throwable {\n        return switch (distributedLock.failStrategy()) {\n            case EXCEPTION -> throw new DistributedLockException(lockKey,\n                DistributedLockException.LockErrorType.ACQUIRE_TIMEOUT,\n                \"Distributed lock acquisition timeout\");\n            case RETURN_NULL -> null;\n            case CONTINUE -> {\n                log.warn(\"Distributed lock acquisition failed, but continuing business logic execution: key={}\", lockKey);\n                yield point.proceed();\n            }\n        };\n    }\n\n    /**\n     * Log lock operation\n     */\n    private void logLockOperation(String lockKey, DistributedLock distributedLock, String operation) {\n        log.info(\"Distributed lock operation: operation={}, key={}, lockType={}, waitTime={}s, leaseTime={}s, \" + \"failStrategy={}, description={}\", operation, lockKey, distributedLock.lockType(),\n                getTimeInSeconds(distributedLock.waitTime(), distributedLock.timeUnit()), getTimeInSeconds(distributedLock.leaseTime(), distributedLock.timeUnit()), distributedLock.failStrategy(), distributedLock.description());\n    }\n","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/hub/src/main/java/com/iflytek/astron/console/hub/aspect/DistributedLockAspect.java#L208-L244","documentation":"When the distributed lock cannot be acquired within waitTime, handleLockFailure delegates to executeFailureStrategy. With failStrategy = EXCEPTION it throws DistributedLockException(ACQUIRE_TIMEOUT) with message 'Distributed lock acquisition timeout'. RETURN_NULL/CONTINUE strategies never throw this.","triggerScenarios":"A @DistributedLock method with EXCEPTION strategy is invoked while another thread/process still holds the lock key beyond waitTime — e.g. concurrent duplicate submissions of the same business key.","commonSituations":"Double-click/duplicate form submission; a long-running holder blocking a scheduled job; waitTime set too short for legitimate contention.","solutions":["Confirm the concurrent holder via logs ('Distributed lock acquisition failed') and decide whether concurrency is expected","Have clients debounce/deduplicate requests (idempotency key, disable button)","Increase waitTime if contention is legitimate and brief","Catch DistributedLockException and return a 'duplicate request in progress' response","Switch to RETURN_NULL/CONTINUE only if skipping execution is safe"],"exampleFix":"// before\n@DistributedLock(key = \"'order:' + #orderId\")\npublic Order create(Long orderId) { ... }\n// after (caller)\ntry { return service.create(orderId); }\ncatch (DistributedLockException e) {\n    throw new BusinessException(ResponseEnum.DUPLICATE_REQUEST);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { return lockedService.call(key); } catch (DistributedLockException e) { if (e.getErrorType() == LockErrorType.ACQUIRE_TIMEOUT) { return duplicateInProgressResponse(); } throw e; }","preventionTips":["Debounce/deduplicate client requests (idempotency keys)","Size waitTime to realistic contention","Alert on repeated ACQUIRE_TIMEOUT for the same key — may indicate a stuck holder","Prefer explicit EXCEPTION strategy over CONTINUE for non-idempotent operations"],"tags":["distributed-lock","concurrency","timeout","redisson"],"backgroundTag":"request-timeout","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}