{"record":{"id":"6878d774af3f3a73","repo":"alibaba/nacos","slug":"500-6878d7","errorCode":"500","errorMessage":"Unknown payload type:{}","messagePattern":"Unknown payload type:(.+?)","errorType":"exception","errorClass":"RemoteException","httpStatus":null,"severity":"critical","filePath":"common/src/main/java/com/alibaba/nacos/common/remote/client/grpc/GrpcUtils.java","lineNumber":133,"sourceCode":"    \n    /**\n     * parse payload to request/response model.\n     *\n     * @param payload payload to be parsed.\n     * @return payload\n     */\n    public static Object parse(Payload payload) {\n        Class classType = PayloadRegistry.getClassByType(payload.getMetadata().getType());\n        if (classType != null) {\n            ByteString byteString = payload.getBody().getValue();\n            ByteBuffer byteBuffer = byteString.asReadOnlyByteBuffer();\n            Object obj = JsonUtils.toObj(new ByteBufferInputStream(byteBuffer), classType);\n            if (obj instanceof Request) {\n                ((Request) obj).putAllHeader(payload.getMetadata().getHeadersMap());\n            }\n            return obj;\n        } else {\n            throw new RemoteException(NacosException.SERVER_ERROR,\n                \"Unknown payload type:\" + payload.getMetadata().getType());\n        }\n    }\n}\n","sourceCodeStart":115,"sourceCodeEnd":138,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/common/src/main/java/com/alibaba/nacos/common/remote/client/grpc/GrpcUtils.java#L115-L138","documentation":"Thrown by GrpcUtils.parse(Payload) when PayloadRegistry.getClassByType(type) returns null — i.e., the payload's metadata type string does not map to any registered Request/Response class. The error is a RemoteException wrapping NacosException.SERVER_ERROR (500). It means the peer (server or client) sent a payload type that this side has never registered, almost always a version or serialization-mismatch problem.","triggerScenarios":"Receiving a gRPC Payload whose metadata.getType() names a class not present in the local PayloadRegistry. Happens when a newer server sends a response type unknown to an older client (or vice-versa), or when a custom payload type was not registered via PayloadRegistry.","commonSituations":"Upgrading the Nacos server while keeping an older client (or the reverse); running a custom client/server build that omits a payload registration; a corrupted or misrouted payload whose type field is garbage.","solutions":["Align client and server to the same Nacos version so every payload type is registered on both sides.","If using custom payload types, ensure PayloadRegistry.register is called on both ends before any request that uses the type.","Inspect the logged unknown type string to identify which payload class is missing, then determine which version introduced it.","Check classpath for conflicting/stale nacos-api jars that may shadow payload registration."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before sending, confirm both sides registered the payload type.\nString type = payload.getMetadata().getType();\nClass<?> cls = PayloadRegistry.getClassByType(type);\nif (cls == null) {\n    throw new IllegalStateException(\n        \"Payload type '\" + type + \"' is unknown to this client/server; check version alignment.\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Object obj = GrpcUtils.parse(payload);\n} catch (RemoteException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR && e.getMessage().startsWith(\"Unknown payload type\")) {\n        // version mismatch — upgrade client or server\n        throw new VersionMismatchException(e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Run the same Nacos version on client and server.","Register any custom payload types on both ends before use.","Avoid stale/conflicting nacos-api jars on the classpath."],"tags":["grpc","serialization","version-mismatch","payload-registry","remote"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}