{"record":{"id":"429cff3d0c23bdf1","repo":"apache/dolphinscheduler","slug":"illegal-protocol-version-version","errorCode":null,"errorMessage":"illegal protocol [version]\" + version","messagePattern":"illegal protocol \\[version\\]\" \\+ version","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/protocal/TransporterDecoder.java","lineNumber":81,"sourceCode":"                Transporter transporter =\n                        Transporter.of(JsonSerializer.deserialize(header, TransporterHeader.class), body);\n                out.add(transporter);\n                checkpoint(State.MAGIC);\n                break;\n            default:\n                log.warn(\"unknown decoder state {}\", state());\n        }\n    }\n\n    private void checkMagic(byte magic) {\n        if (magic != Transporter.MAGIC) {\n            throw new IllegalArgumentException(\"illegal packet [magic]\" + magic);\n        }\n    }\n\n    private void checkVersion(byte version) {\n        if (version != Transporter.VERSION) {\n            throw new IllegalArgumentException(\"illegal protocol [version]\" + version);\n        }\n    }\n\n    enum State {\n        MAGIC,\n        VERSION,\n        HEADER_LENGTH,\n        HEADER,\n        BODY_LENGTH,\n        BODY;\n    }\n\n}\n","sourceCodeStart":63,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/protocal/TransporterDecoder.java#L63-L95","documentation":"TransporterDecoder.checkVersion validates the protocol version byte of an inbound packet against Transporter.VERSION. A mismatch means the peer speaks a different (likely older or newer) version of the DolphinScheduler wire protocol.","triggerScenarios":"decode() reads the version byte after a valid magic byte and it differs from Transporter.VERSION — typically mixed DolphinScheduler versions in the cluster communicating over RPC.","commonSituations":"Rolling upgrade with masters/ workers on different versions; a custom build or patched fork that changed Transporter.VERSION; a gateway forwarding requests from an incompatible cluster.","solutions":["Align all cluster nodes to the same DolphinScheduler version","Check Transporter.VERSION in both deployments and rebuild clients/servers from matching sources","During upgrades, drain old-version nodes before new-version nodes send traffic to them","Verify no intermediate proxy forwards stale packets between clusters"],"exampleFix":"// before\n// master on 3.1.x RPC to worker on 3.2.x (version byte differs)\nmasters: [node-a:1234] // 3.1.x\nworkers: [node-b:1234] // 3.2.x\n// after\nmasters: [node-a:1234] // 3.2.x\nworkers: [node-b:1234] // 3.2.x","handlingStrategy":"validation","validationCode":"// check cluster version homogeneity before RPC traffic\nString serverVer = fetchServerVersion(host, port);\nif (!serverVer.equals(clientVersion)) {\n    throw new IllegalStateException(\"Protocol version mismatch: client \" + clientVersion + \" vs server \" + serverVer);\n}","typeGuard":null,"tryCatchPattern":"try {\n    sendRpc(request);\n} catch (Exception e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"illegal protocol [version]\")) {\n        // mark node incompatible; route to same-version node or halt upgrade\n    }\n    throw e;\n}","preventionTips":["Upgrade masters and workers together, or gate traffic until versions match","Pin all nodes to the same release in IaC/cluster tooling","Test RPC between versions in staging before rolling upgrades"],"tags":["netty","protocol","version-mismatch","rpc"],"backgroundTag":"incompatible-source-type","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}