{"record":{"id":"f6242eacddc31819","repo":"apache/incubator-seata","slug":"unsupported-version-version","errorCode":null,"errorMessage":"Unsupported version: {version}","messagePattern":"Unsupported version: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/rpc/netty/MultiProtocolDecoder.java","lineNumber":143,"sourceCode":"                version = decideVersion(decoded);\n            }\n\n            if (decoded instanceof ByteBuf) {\n                frame = (ByteBuf) decoded;\n                // Ensure version is within supported range\n                if (version > maxCurrentVersion) {\n                    version = maxCurrentVersion;\n                    LOGGER.error(\n                            \"Detected version {} is greater than max supported version {}, using max supported version.\",\n                            version,\n                            maxCurrentVersion);\n                }\n                ProtocolDecoder decoder = protocolDecoderMap.get(version);\n                ProtocolEncoder encoder = protocolEncoderMap.get(version);\n\n                try {\n                    if (decoder == null || encoder == null) {\n                        throw new UnsupportedOperationException(\"Unsupported version: \" + version);\n                    }\n                    return decoder.decodeFrame(frame);\n                } finally {\n                    if (version != ProtocolConstants.VERSION_0) {\n                        frame.release();\n                    }\n                    // Remove existing encoder if it exists (for client-side compatibility)\n                    removeExistingEncoder(ctx, encoder);\n                    ctx.pipeline().addLast((ChannelHandler) decoder);\n                    ctx.pipeline().addLast((ChannelHandler) encoder);\n                    if (channelHandlers != null) {\n                        ctx.pipeline().addLast(channelHandlers);\n                    }\n                    ctx.pipeline().remove(this);\n                }\n            }\n        } catch (Exception exx) {\n            LOGGER.error(\"Decode frame error, cause: {}\", exx.getMessage());","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/rpc/netty/MultiProtocolDecoder.java#L125-L161","documentation":"Thrown by MultiProtocolDecoder when an inbound frame's protocol version byte maps to no registered ProtocolDecoder/ProtocolEncoder pair. Seata's multi-protocol support keeps per-version codecs; a version that is neither in the map (and not clamped to maxCurrentVersion because it was below the minimum or simply absent) hits this branch and the pipeline for that channel cannot be installed.","triggerScenarios":"A client connecting with a protocol version the server build does not carry a codec for — typically a newer client talking to an older server where the version byte is lower than the server's minimum supported (so the max-version clamp does not apply), or a custom protocol version registered on one side only.","commonSituations":"Version skew between seata client and server (e.g. client 2.x vs server 1.x); custom transport protocol extensions deployed only to the server or only to the client; corrupted frames shifting the version byte.","solutions":["Align seata client and server versions (same minor release line on both ends)","If you intentionally run mixed versions, check which protocol versions both builds register in MultiProtocolDecoder and pick one both support","Inspect the first bytes of the frame (magic code + version) with a wire capture if frames may be corrupted or proxied by something that rewrites bytes","Set the protocol explicitly (seata.client.protocol / seata.server.protocol) rather than relying on negotiation"],"exampleFix":"# before: mismatched versions\nclient: org.apache.seata:seata-all:2.1.0\nserver: seataio/seata-server:1.7.0\n\n# after\nclient: org.apache.seata:seata-all:2.1.0\nserver: seataio/seata-server:2.1.0","handlingStrategy":"validation","validationCode":"// before connecting, confirm version compatibility\nint v = ProtocolConstants.CURRENT_VERSION; // what this build supports\n// ensure client and server manifests declare the same seata version","typeGuard":null,"tryCatchPattern":"catch (UnsupportedOperationException e) {\n    if (e.getMessage().startsWith(\"Unsupported version\")) {\n        // abort connection: version skew; pin matching versions and restart\n    }\n}","preventionTips":["Pin identical seata versions on client and server (dependencyManagement)","Add a startup banner/log of negotiated protocol version to catch skew early","Run contract tests across versions before upgrading one side"],"tags":["protocol","version-mismatch","decoder","netty"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}