alibaba/nacos · critical · RemoteException

500

500

Error message

Unknown payload type:{}

What it means

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.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/remote/client/grpc/GrpcUtils.java:133

    
    /**
     * parse payload to request/response model.
     *
     * @param payload payload to be parsed.
     * @return payload
     */
    public static Object parse(Payload payload) {
        Class classType = PayloadRegistry.getClassByType(payload.getMetadata().getType());
        if (classType != null) {
            ByteString byteString = payload.getBody().getValue();
            ByteBuffer byteBuffer = byteString.asReadOnlyByteBuffer();
            Object obj = JsonUtils.toObj(new ByteBufferInputStream(byteBuffer), classType);
            if (obj instanceof Request) {
                ((Request) obj).putAllHeader(payload.getMetadata().getHeadersMap());
            }
            return obj;
        } else {
            throw new RemoteException(NacosException.SERVER_ERROR,
                "Unknown payload type:" + payload.getMetadata().getType());
        }
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Align client and server to the same Nacos version so every payload type is registered on both sides.
2. If using custom payload types, ensure PayloadRegistry.register is called on both ends before any request that uses the type.
3. Inspect the logged unknown type string to identify which payload class is missing, then determine which version introduced it.
4. Check classpath for conflicting/stale nacos-api jars that may shadow payload registration.

// Before sending, confirm both sides registered the payload type.
String type = payload.getMetadata().getType();
Class<?> cls = PayloadRegistry.getClassByType(type);
if (cls == null) {
    throw new IllegalStateException(
        "Payload type '" + type + "' is unknown to this client/server; check version alignment.");
}

try {
    Object obj = GrpcUtils.parse(payload);
} catch (RemoteException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR && e.getMessage().startsWith("Unknown payload type")) {
        // version mismatch — upgrade client or server
        throw new VersionMismatchException(e.getMessage());
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• SERVER_NOT_IMPLEMENTED
• 501
• 500
• {}
• PARAMETER_MISSING

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