apache/dolphinscheduler · error · IllegalArgumentException

illegal protocol [version]" + version

Error message

illegal protocol [version]" + version

What it means

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.

Solutions

  1. Align all cluster nodes to the same DolphinScheduler version
  2. Check Transporter.VERSION in both deployments and rebuild clients/servers from matching sources
  3. During upgrades, drain old-version nodes before new-version nodes send traffic to them
  4. Verify no intermediate proxy forwards stale packets between clusters

Example fix

// before
// master on 3.1.x RPC to worker on 3.2.x (version byte differs)
masters: [node-a:1234] // 3.1.x
workers: [node-b:1234] // 3.2.x
// after
masters: [node-a:1234] // 3.2.x
workers: [node-b:1234] // 3.2.x
Defensive patterns

Strategy: validation

Validate before calling

// check cluster version homogeneity before RPC traffic
String serverVer = fetchServerVersion(host, port);
if (!serverVer.equals(clientVersion)) {
    throw new IllegalStateException("Protocol version mismatch: client " + clientVersion + " vs server " + serverVer);
}

Try / catch

try {
    sendRpc(request);
} catch (Exception e) {
    if (e.getMessage() != null && e.getMessage().contains("illegal protocol [version]")) {
        // mark node incompatible; route to same-version node or halt upgrade
    }
    throw e;
}

Prevention

When it happens

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

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

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

                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)