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.

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)

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.