iflytek/astron-agent · error · DistributedLockException

KEY_PARSE_FAILED

KEY_PARSE_FAILED

Error message

Lock key parsing failed: 

What it means

parseLockKey evaluates the @DistributedLock key expression with SpEL and throws DistributedLockException(KEY_PARSE_FAILED) if parsing or evaluation throws. The lock never gets acquired because the lock key itself could not be built.

Solutions

1. Check log 'Failed to parse lock key: keyExpression=...' and fix the SpEL expression
2. Verify parameter names match actual method signatures (compile with -parameters)
3. Guard expression operands against null (e.g. #id != null ? #id : 'unknown')
4. Test the expression with a simple constant key first, then add SpEL gradually

Example fix

// before
@DistributedLock(key = "'bot:' + #req.bot.id")
public void run(Req req) { ... }
// after
@DistributedLock(key = "'bot:' + (#req?.bot?.id ?: 'none')")
public void run(Req req) { ... }

// pre-check SpEL operands: assert args != null && args.getId() != null before invoking the locked method

try { return service.lockedMethod(arg); } catch (DistributedLockException e) { if (e.getErrorType() == LockErrorType.KEY_PARSE_FAILED) { throw new IllegalStateException("bad lock key expression", e); } throw e; }

When it happens

Trigger: Key SpEL expression references a null method argument, wrong property name, unsupported syntax, or evaluation throws (e.g. calling a method on null inside the expression).

Common situations: Typo in SpEL property (#userId vs #user_id); expression uses a parameter name removed by compilation without -parameters; applying @DistributedLock to a method whose args don't match the expression.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

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

Appendix: source

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

            // This check is a fast path for strings without any dynamic content
            if (!keyExpression.contains("#{")) {
                return keyExpression;
            }

            MethodSignature signature = (MethodSignature) point.getSignature();
            Method method = signature.getMethod();
            Object[] args = point.getArgs();

            EvaluationContext context = new MethodBasedEvaluationContext(point.getTarget(), method, args, nameDiscoverer);

            ParserContext parserContext = new TemplateParserContext();
            Expression expression = parser.parseExpression(keyExpression, parserContext);
            Object result = expression.getValue(context);

            return result != null ? result.toString() : keyExpression;
        } catch (Exception e) {
            log.error("Failed to parse lock key: keyExpression={}, error={}", keyExpression, e.getMessage(), e);
            throw new DistributedLockException(keyExpression, DistributedLockException.LockErrorType.KEY_PARSE_FAILED, "Lock key parsing failed: " + e.getMessage(), e);
        }
    }

    /**
     * Get corresponding lock object based on lock type
     */
    private RLock getLock(String lockKey, DistributedLock.LockType lockType) {
        try {
            return switch (lockType) {
                case REENTRANT -> redissonClient.getLock(lockKey);
                case FAIR -> redissonClient.getFairLock(lockKey);
                case READ -> {
                    RReadWriteLock readWriteLock = redissonClient.getReadWriteLock(lockKey);
                    yield readWriteLock.readLock();
                }
                case WRITE -> {
                    RReadWriteLock readWriteLock = redissonClient.getReadWriteLock(lockKey);
                    yield readWriteLock.writeLock();

View on GitHub (pinned to 5e758547a8)