apache/seatunnel · warning

Unrecognized command prefix, got

Error message

Unrecognized command prefix, got: {}

What it means

Logged in dispatch() when IngressCommand.matchPrefix cannot map the first line of a request to any known command (COMMIT or BATCH). The server replies with the BAD_REQUEST response code and keeps the connection open. It indicates the client is speaking a protocol the server does not recognize.

Solutions

1. Log the abbreviated request (EdgeSocketLogUtils.abbreviateForLog output) and align the collector with the expected 'COMMIT <id>' / 'BATCH <id>:<payload>' format.
2. Check collector and server versions for protocol compatibility.
3. Ensure the collector writes complete, newline-terminated command lines.
4. Verify no non-collector client (e.g. load balancer health check) is hitting this port.

Example fix

// before (client)
writer.write(batchId + ":" + payload); // missing command prefix
// after
writer.write("BATCH " + batchId + ":" + payload + "\n");

if (line == null || !(line.startsWith("COMMIT ") || line.startsWith("BATCH "))) { throw new IllegalArgumentException("request must start with COMMIT or BATCH prefix: " + line); }

When it happens

Trigger: receiveLoop reads a line and hands it to dispatch; the line's prefix matches no IngressCommand — e.g. empty line, wrong/misspelled command word, or a raw payload sent before the BATCH prefix.

Common situations: Collector client using an older/newer protocol version than the server, sending payloads without the required command prefix, TCP framing issues splitting or corrupting the first line, a health-check probe sending plain HTTP to the raw TCP port.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Malformed BATCH request, missing payload separator
• Collector authentication failed from
• Command is not dispatched yet
• Invalid BATCH batchId in request
• Invalid COMMIT batchId in request

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-edge-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/edgesocket/protocol/IngressProtocolHandler.java:100

        while (isActive.getAsBoolean()) {
            String record;
            try {
                record = channel.readLine();
            } catch (SocketTimeoutException timeoutException) {
                continue;
            }
            if (record == null) {
                return;
            }
            channel.writeLine(dispatch(record));
        }
    }

    private String dispatch(String request) {
        IngressCommand command = IngressCommand.matchPrefix(request);
        if (command == null) {
            log.warn(
                    "Unrecognized command prefix, got: {}",
                    EdgeSocketLogUtils.abbreviateForLog(request));
            return EdgeSocketResponseCode.BAD_REQUEST.getCode();
        }
        switch (command) {
            case COMMIT:
                return dispatchCommit(request);
            case BATCH:
                return dispatchBatch(request);
            default:
                log.warn("Command {} is not dispatched yet", command);
                return EdgeSocketResponseCode.BAD_REQUEST.getCode();
        }
    }

    private String dispatchCommit(String request) {
        Long batchId = parseBatchId(request, IngressCommand.COMMIT.prefix());
        if (batchId == null || batchId <= 0) {
            log.warn(

View on GitHub (pinned to cf67b549a7)