alibaba/nacos · error · NacosRuntimeException

501

501

Error message

Request Nacos server version is too low, not support lock feature.

What it means

Thrown by LockGrpcClient.lock(LockInstance) when isAbilitySupportedByServer() returns false, i.e. the connected server does not advertise the SERVER_DISTRIBUTED_LOCK ability. This is a version/capability gate: the distributed lock feature requires a Nacos server new enough to support it. The error code is NacosException.SERVER_NOT_IMPLEMENTED (501) wrapped in a NacosRuntimeException.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/lock/remote/grpc/LockGrpcClient.java:139

                    if (future != null) {
                        future.complete(notification.getNotificationType());
                    }
                    return new LockNotificationResponse();
                }
                return null;
            }
        });
    }
    
    private void start(ServerListFactory serverListFactory) throws NacosException {
        rpcClient.serverListFactory(serverListFactory);
        rpcClient.start();
    }
    
    @Override
    public Boolean lock(LockInstance instance) throws NacosException {
        if (!isAbilitySupportedByServer()) {
            throw new NacosRuntimeException(NacosException.SERVER_NOT_IMPLEMENTED,
                "Request Nacos server version is too low, not support lock feature.");
        }
        // Defensive copy to avoid mutating the caller's object.
        LockInstance copy = new LockInstance();
        copy.setKey(instance.getKey());
        copy.setLockType(instance.getLockType());
        copy.setOwner(instance.getOwner());
        copy.setExpiredTime(instance.getExpiredTime());
        copy.setWaitTime(instance.getWaitTime());
        copy.setParams(instance.getParams());
        
        long waitTime = copy.getWaitTime();
        if (waitTime == 0) {
            waitTime = DEFAULT_REQUEST_TIMEOUT_MS;
        }
        boolean useWaitQueue = waitTime > 0;
        long deadline = useWaitQueue ? System.currentTimeMillis() + waitTime : 0;
        boolean acquired = false;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Upgrade the Nacos server to a version that supports distributed locks (3.x with the lock module enabled).
2. Verify the server advertises the ability: inspect the connection setup / ability negotiation (AbilityKey.SERVER_DISTRIBUTED_LOCK).
3. In a mixed-version cluster, ensure the client connects to an upgraded node, or upgrade all nodes.
4. Gate client code on the ability check before attempting lock operations and degrade gracefully.

Example fix

// before
Boolean ok = lockGrpcClient.lock(instance); // throws 501 on old server

// after — guard with ability check or upgrade server
if (rpcClient.getConnectionAbility(AbilityKey.SERVER_DISTRIBUTED_LOCK) == AbilityStatus.SUPPORTED) {
    lockGrpcClient.lock(instance);
} else {
    throw new IllegalStateException("Distributed lock not supported by connected server");
}

if (rpcClient.getConnectionAbility(AbilityKey.SERVER_DISTRIBUTED_LOCK) == AbilityStatus.SUPPORTED) {
    lockGrpcClient.lock(instance);
} else {
    throw new IllegalStateException("Server lacks distributed lock support");
}

try { lockGrpcClient.lock(instance); } catch (NacosRuntimeException e) { if (e.getCode() == NacosException.SERVER_NOT_IMPLEMENTED) { /* upgrade server or degrade */ } else throw e; }

When it happens

Trigger: Connecting a client that supports distributed locks to an older Nacos server that predates the lock module; the gRPC connection's ability negotiation reporting SERVER_DISTRIBUTED_LOCK as UNSUPPORTED; a custom/non-standard server build that omits the lock handler.

Common situations: Upgrading the client SDK but not the server; pointing a new client at a legacy 2.x server cluster; mixed-version cluster where the currently connected node is old; server built without the lock plugin enabled.

Related errors

• SERVER_NOT_IMPLEMENTED
• 501
• SERVER_ERROR
• Failed to acquire lock: {}
• Failed to unlock: {}

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