iflytek/astron-agent · warning · DistributedLockException

ACQUIRE_TIMEOUT

ACQUIRE_TIMEOUT

Error message

Distributed lock acquisition timeout

What it means

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.

Solutions

1. Confirm the concurrent holder via logs ('Distributed lock acquisition failed') and decide whether concurrency is expected
2. Have clients debounce/deduplicate requests (idempotency key, disable button)
3. Increase waitTime if contention is legitimate and brief
4. Catch DistributedLockException and return a 'duplicate request in progress' response
5. Switch to RETURN_NULL/CONTINUE only if skipping execution is safe

Example fix

// before
@DistributedLock(key = "'order:' + #orderId")
public Order create(Long orderId) { ... }
// after (caller)
try { return service.create(orderId); }
catch (DistributedLockException e) {
    throw new BusinessException(ResponseEnum.DUPLICATE_REQUEST);
}

try { return lockedService.call(key); } catch (DistributedLockException e) { if (e.getErrorType() == LockErrorType.ACQUIRE_TIMEOUT) { return duplicateInProgressResponse(); } throw e; }

When it happens

Trigger: 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.

Common situations: Double-click/duplicate form submission; a long-running holder blocking a scheduled job; waitTime set too short for legitimate contention.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Timed out acquiring distributed lock, please try again later
• Distributed lock acquisition timeout, please try again later
• RELEASE_FAILED
• REDIS_CONNECTION_ERROR
• KEY_PARSE_FAILED

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/e64aec6bea043fce. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/hub/src/main/java/com/iflytek/astron/console/hub/aspect/DistributedLockAspect.java:226

    /**
     * Handle lock acquisition failure
     */
    private Object handleLockFailure(String lockKey, DistributedLock distributedLock,
            ProceedingJoinPoint point) throws Throwable {
        logLockFailure(lockKey, distributedLock);
        return executeFailureStrategy(lockKey, distributedLock, point);
    }

    private void logLockFailure(String lockKey, DistributedLock distributedLock) {
        String message = String.format("Failed to acquire distributed lock: key=%s, waitTime=%d%s",
                lockKey, distributedLock.waitTime(), distributedLock.timeUnit().name().toLowerCase());
        log.warn(message);
    }

    private Object executeFailureStrategy(String lockKey, DistributedLock distributedLock,
                                        ProceedingJoinPoint point) throws Throwable {
        return switch (distributedLock.failStrategy()) {
            case EXCEPTION -> throw new DistributedLockException(lockKey,
                DistributedLockException.LockErrorType.ACQUIRE_TIMEOUT,
                "Distributed lock acquisition timeout");
            case RETURN_NULL -> null;
            case CONTINUE -> {
                log.warn("Distributed lock acquisition failed, but continuing business logic execution: key={}", lockKey);
                yield point.proceed();
            }
        };
    }

    /**
     * Log lock operation
     */
    private void logLockOperation(String lockKey, DistributedLock distributedLock, String operation) {
        log.info("Distributed lock operation: operation={}, key={}, lockType={}, waitTime={}s, leaseTime={}s, " + "failStrategy={}, description={}", operation, lockKey, distributedLock.lockType(),
                getTimeInSeconds(distributedLock.waitTime(), distributedLock.timeUnit()), getTimeInSeconds(distributedLock.leaseTime(), distributedLock.timeUnit()), distributedLock.failStrategy(), distributedLock.description());
    }

View on GitHub (pinned to 5e758547a8)