apache/seatunnel · error · IllegalArgumentException

batchId must be positive

Error message

batchId must be positive

What it means

EdgeSocketLineTransport.sendBatchUntilReceived validates its batchId argument before writing the BATCH line to the socket. A batchId of zero or negative is rejected with this IllegalArgumentException because the wire protocol requires a positive, monotonically increasing batch identifier so the collector can deduplicate and order batches.

Solutions

1. Initialize the batch counter to 1 (or verify it is incremented before the first send)
2. Check the code path that generates batchId and add an assertion/validation at generation time
3. If a persisted counter is used, verify the restore logic does not yield 0 on a fresh start
4. Clamp or regenerate: if batchId <= 0, assign a new positive value before calling send

Example fix

// before
client.send(batchId, payload); // batchId may be 0
// after
if (batchId <= 0) { batchId = nextBatchId(); }
client.send(batchId, payload);

if (batchId <= 0) throw new IllegalArgumentException("batchId must be positive, got " + batchId);

try { client.send(batchId, payload); } catch (IllegalArgumentException e) { batchId = counter.next(); client.send(batchId, payload); }

When it happens

Trigger: Calling sendBatchUntilReceived (or the higher-level EdgeTransportClient.send) with batchId <= 0, e.g. an uninitialized/zero batch counter or a counter reset to 0/−1 after restart.

Common situations: Batch id counter initialized to 0 and never incremented before first send; persisted counter restored incorrectly after agent restart; integer overflow wrapping to negative in long-running agents.

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

• Invalid BATCH batchId in request
• Invalid COMMIT batchId in request
• AmazonDocumentDB option '' must be a valid BSON/JSON…
• AmazonDocumentDB option '' must not be blank
• API-01

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/2eaf88f3f9e98fd4. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-transport/src/main/java/org/apache/seatunnel/edge/agent/transport/socket/EdgeSocketLineTransport.java:43

final class EdgeSocketLineTransport {

    private final EdgeTransportConfig config;

    EdgeSocketLineTransport(EdgeTransportConfig config) {
        this.config = config;
    }

    void authenticate(BufferedReader reader, BufferedWriter writer) throws IOException {
        writeLine(writer, EdgeSocketProtocol.AUTH_LINE_PREFIX + config.getToken());
        handleAuthResponse(readLineNormalized(reader));
    }

    void sendBatchUntilReceived(
            BufferedReader reader, BufferedWriter writer, long batchId, String payload)
            throws IOException, InterruptedException {
        if (batchId <= 0) {
            throw new IllegalArgumentException("batchId must be positive");
        }
        String line = EdgeSocketProtocol.BATCH_PREFIX + batchId + ':' + payload;
        int attempts = 0;
        while (attempts < config.getMaxBatchSendAttempts()) {
            writeLine(writer, line);
            String reply = readLineNormalized(reader);
            if (EdgeSocketProtocol.RESP_RECEIVED.equals(reply)) {
                return;
            }
            if (EdgeSocketProtocol.RESP_RETRY.equals(reply)) {
                attempts++;
                EdgeTransportConfig.sleepQuiet(
                        EdgeTransportConfig.computeBackoffMillis(
                                attempts - 1,
                                config.getInitialBackoffMs(),
                                config.getMaxBackoffMs()));
                continue;
            }

View on GitHub (pinned to cf67b549a7)