{"record":{"id":"0b6c005398c4019c","repo":"apache/dolphinscheduler","slug":"illegal-packet-magic-magic","errorCode":null,"errorMessage":"illegal packet [magic]\" + magic","messagePattern":"illegal packet \\[magic\\]\" \\+ magic","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":75,"sourceCode":"            case BODY_LENGTH:\n                bodyLength = in.readInt();\n                checkpoint(State.BODY);\n            case BODY:\n                body = new byte[bodyLength];\n                in.readBytes(body);\n                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","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/protocal/TransporterDecoder.java#L57-L93","documentation":"TransporterDecoder.checkMagic validates the first byte of each incoming Netty frame against Transporter.MAGIC. A mismatch means the received bytes are not a valid DolphinScheduler transport packet, so decoding is aborted immediately to avoid parsing garbage.","triggerScenarios":"decode() reads the magic byte of an inbound ByteBuf and it differs from Transporter.MAGIC — e.g. the peer sent data that is not this RPC protocol (wrong port, plain HTTP, TLS bytes, or a corrupted stream).","commonSituations":"Client pointed at the wrong port where another service listens; a proxy/load balancer speaking a different protocol in front of the server; one endpoint on a different DolphinScheduler version with a changed protocol; sending raw data over the channel manually.","solutions":["Verify both endpoints point at the correct DolphinScheduler RPC port with no foreign service bound there","Ensure client and server run compatible DolphinScheduler versions (same Transporter.MAGIC)","Check for TLS/proxies intercepting the connection and sending non-plaintext protocol bytes","Confirm no custom code writes directly to the channel bypassing the encoder"],"exampleFix":"// before\n// client configured against port 5678 which runs an HTTP server\nRpcClient client = new RpcClient(\"192.168.1.10:5678\");\n// after\n// point at the actual DolphinScheduler master/worker RPC port\nRpcClient client = new RpcClient(\"192.168.1.10:1234\");","handlingStrategy":"validation","validationCode":"// confirm the endpoint is really a DolphinScheduler RPC server before connecting\nInetSocketAddress addr = resolve(host, port);\nif (!isKnownDolphinSchedulerPort(addr)) {\n    throw new IllegalStateException(addr + \" is not a DolphinScheduler RPC endpoint\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    sendRpc(request);\n} catch (Exception e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"illegal packet [magic]\")) {\n        // stop talking to this endpoint: wrong service/port or incompatible build\n    }\n    throw e;\n}","preventionTips":["Verify port assignments between services (no HTTP service on an RPC port)","Avoid TLS/proxy layers that alter raw protocol bytes on RPC ports","Keep client and server on the same DolphinScheduler build"],"tags":["netty","protocol","decoder","rpc"],"backgroundTag":"invalid-argument-value","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"}