alibaba/nacos · error · NacosLockException

Failed to acquire lock: {}

Error message

Failed to acquire lock: {}

What it means

Thrown by NacosLock.lock() when a NacosException (not InterruptedException) occurs during the acquisition loop — typically a gRPC transport error, server-side rejection, or connection failure. The method logs the error, cancels the server-side wait, cleans up the ThreadLocal count, and wraps the original NacosException in a NacosLockException with the message "Failed to acquire lock: <key>".

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/lock/NacosLock.java:172

                    if (result.getReentrantCount() == 1) {
                        watchdog.register(key, grpcClient, instance);
                    }
                    return;
                }
                firstAttempt = false;
                grpcClient.waitForNotification(key, currentOwner(), NOTIFICATION_POLL_TIMEOUT_MS);
            } catch (InterruptedException e) {
                // Clear interrupt flag so gRPC cancel request doesn't throw,
                // then restore it after the synchronous server-side cleanup.
                grpcClient.cancelWait(key, lockType, currentOwner());
                Thread.currentThread().interrupt();
                localReentrantCount.remove();
                throw new NacosLockException("Lock interrupted", e);
            } catch (NacosException e) {
                LOGGER.error("Failed to acquire lock, key={}", key, e);
                grpcClient.cancelWait(key, lockType, currentOwner());
                localReentrantCount.remove();
                throw new NacosLockException("Failed to acquire lock: " + key, e);
            }
        }
    }
    
    @Override
    public void lockInterruptibly() throws InterruptedException {
        checkReentrantGuard();
        boolean firstAttempt = true;
        while (true) {
            if (Thread.interrupted()) {
                if (!firstAttempt) {
                    grpcClient.cancelWait(key, lockType, currentOwner());
                }
                throw new InterruptedException();
            }
            try {
                LockInstance instance = buildInstance(-1);
                instance.setWaitTime(DEFAULT_SERVER_WAIT_TIME_MS);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Check the Nacos server health and gRPC connectivity (port 9849 for gRPC).
2. Examine the wrapped NacosException cause for the specific error code (e.g. connection refused, UNAVAILABLE).
3. Implement a retry-with-backoff strategy for transient transport errors.
4. Ensure the gRPC connection is established and authenticated before acquiring locks.
5. Verify the server version supports the distributed lock feature.

Example fix

// before
lock.lock(); // throws NacosLockException on gRPC failure

// after — retry with backoff
int attempts = 0;
while (true) {
    try {
        lock.lock();
        break;
    } catch (NacosLockException e) {
        if (++attempts > MAX_RETRIES) throw e;
        Thread.sleep(backoffMillis(attempts));
    }
}

// Pre-check: verify gRPC connectivity before acquiring
boolean isServerReachable(LockGrpcClient client) {
    try {
        return client.isAlive(); // or a lightweight health check
    } catch (Exception e) {
        return false;
    }
}

// N/A — transport errors are runtime failures, not type-level.

int attempts = 0;
while (true) {
    try {
        lock.lock();
        break;
    } catch (NacosLockException e) {
        Throwable cause = e.getCause();
        if (cause instanceof NacosException && isTransient((NacosException) cause)) {
            if (++attempts > MAX_RETRIES) throw e;
            Thread.sleep(backoffMillis(attempts));
        } else {
            throw e;
        }
    }
}

When it happens

Trigger: The gRPC client encounters a transport error (connection lost, server unreachable) during lockWithResult or waitForNotification; the server returns an error response that maps to a NacosException; the lock service is temporarily unavailable or the server is restarting.

Common situations: Network partition or gRPC channel reset between client and Nacos server; the Nacos server is down or restarting; the gRPC connection was idle-closed; authentication token expired mid-acquisition; the server is overloaded and rejects the request.

Related errors

• Failed to unlock: {}
• 500
• -401
• request timeout after {timeout} milliseconds, requestId={req
• SERVER_ERROR

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/1b987bdc7fd12add. Report an issue: GitHub.