{"record":{"id":"aa3c3865baf84b67","repo":"alibaba/nacos","slug":"501-aa3c38","errorCode":"501","errorMessage":"Request Nacos server version is too low, not support lock feature.","messagePattern":"Request Nacos server version is too low, not support lock feature\\.","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/lock/remote/grpc/LockGrpcClient.java","lineNumber":139,"sourceCode":"                    if (future != null) {\n                        future.complete(notification.getNotificationType());\n                    }\n                    return new LockNotificationResponse();\n                }\n                return null;\n            }\n        });\n    }\n    \n    private void start(ServerListFactory serverListFactory) throws NacosException {\n        rpcClient.serverListFactory(serverListFactory);\n        rpcClient.start();\n    }\n    \n    @Override\n    public Boolean lock(LockInstance instance) throws NacosException {\n        if (!isAbilitySupportedByServer()) {\n            throw new NacosRuntimeException(NacosException.SERVER_NOT_IMPLEMENTED,\n                \"Request Nacos server version is too low, not support lock feature.\");\n        }\n        // Defensive copy to avoid mutating the caller's object.\n        LockInstance copy = new LockInstance();\n        copy.setKey(instance.getKey());\n        copy.setLockType(instance.getLockType());\n        copy.setOwner(instance.getOwner());\n        copy.setExpiredTime(instance.getExpiredTime());\n        copy.setWaitTime(instance.getWaitTime());\n        copy.setParams(instance.getParams());\n        \n        long waitTime = copy.getWaitTime();\n        if (waitTime == 0) {\n            waitTime = DEFAULT_REQUEST_TIMEOUT_MS;\n        }\n        boolean useWaitQueue = waitTime > 0;\n        long deadline = useWaitQueue ? System.currentTimeMillis() + waitTime : 0;\n        boolean acquired = false;","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/lock/remote/grpc/LockGrpcClient.java#L121-L157","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the Nacos server to a version that supports distributed locks (3.x with the lock module enabled).","Verify the server advertises the ability: inspect the connection setup / ability negotiation (AbilityKey.SERVER_DISTRIBUTED_LOCK).","In a mixed-version cluster, ensure the client connects to an upgraded node, or upgrade all nodes.","Gate client code on the ability check before attempting lock operations and degrade gracefully."],"exampleFix":"// before\nBoolean ok = lockGrpcClient.lock(instance); // throws 501 on old server\n\n// after — guard with ability check or upgrade server\nif (rpcClient.getConnectionAbility(AbilityKey.SERVER_DISTRIBUTED_LOCK) == AbilityStatus.SUPPORTED) {\n    lockGrpcClient.lock(instance);\n} else {\n    throw new IllegalStateException(\"Distributed lock not supported by connected server\");\n}","handlingStrategy":"validation","validationCode":"if (rpcClient.getConnectionAbility(AbilityKey.SERVER_DISTRIBUTED_LOCK) == AbilityStatus.SUPPORTED) {\n    lockGrpcClient.lock(instance);\n} else {\n    throw new IllegalStateException(\"Server lacks distributed lock support\");\n}","typeGuard":null,"tryCatchPattern":"try { lockGrpcClient.lock(instance); } catch (NacosRuntimeException e) { if (e.getCode() == NacosException.SERVER_NOT_IMPLEMENTED) { /* upgrade server or degrade */ } else throw e; }","preventionTips":["Upgrade the server to a version supporting distributed locks.","Check ability once at connection time and fail fast if unsupported.","In mixed clusters, ensure all failover nodes support the feature."],"tags":["lock","version-mismatch","ability-negotiation","grpc","server-not-implemented"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}