apache/dolphinscheduler · error · IllegalArgumentException

illegal packet [magic]" + magic

Error message

illegal packet [magic]" + magic

What it means

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.

Source

Thrown at dolphinscheduler-extract/dolphinscheduler-extract-base/src/main/java/org/apache/dolphinscheduler/extract/base/protocal/TransporterDecoder.java:75

            case BODY_LENGTH:
                bodyLength = in.readInt();
                checkpoint(State.BODY);
            case BODY:
                body = new byte[bodyLength];
                in.readBytes(body);
                Transporter transporter =
                        Transporter.of(JsonSerializer.deserialize(header, TransporterHeader.class), body);
                out.add(transporter);
                checkpoint(State.MAGIC);
                break;
            default:
                log.warn("unknown decoder state {}", state());
        }
    }

    private void checkMagic(byte magic) {
        if (magic != Transporter.MAGIC) {
            throw new IllegalArgumentException("illegal packet [magic]" + magic);
        }
    }

    private void checkVersion(byte version) {
        if (version != Transporter.VERSION) {
            throw new IllegalArgumentException("illegal protocol [version]" + version);
        }
    }

    enum State {
        MAGIC,
        VERSION,
        HEADER_LENGTH,
        HEADER,
        BODY_LENGTH,
        BODY;
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify both endpoints point at the correct DolphinScheduler RPC port with no foreign service bound there
  2. Ensure client and server run compatible DolphinScheduler versions (same Transporter.MAGIC)
  3. Check for TLS/proxies intercepting the connection and sending non-plaintext protocol bytes
  4. Confirm no custom code writes directly to the channel bypassing the encoder

Example fix

// before
// client configured against port 5678 which runs an HTTP server
RpcClient client = new RpcClient("192.168.1.10:5678");
// after
// point at the actual DolphinScheduler master/worker RPC port
RpcClient client = new RpcClient("192.168.1.10:1234");
Defensive patterns

Strategy: validation

Validate before calling

// confirm the endpoint is really a DolphinScheduler RPC server before connecting
InetSocketAddress addr = resolve(host, port);
if (!isKnownDolphinSchedulerPort(addr)) {
    throw new IllegalStateException(addr + " is not a DolphinScheduler RPC endpoint");
}

Try / catch

try {
    sendRpc(request);
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("illegal packet [magic]")) {
        // stop talking to this endpoint: wrong service/port or incompatible build
    }
    throw e;
}

Prevention

When it happens

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

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

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/0b6c005398c4019c. Report an issue: GitHub.