apache/seatunnel · error · FileConnectorException

BINARY_FILE_PART_ORDER_ERROR

BINARY_FILE_PART_ORDER_ERROR

Error message

Last order is " + partIndexMap.get(filePath) + ", but get " + partIndex

What it means

Binary files are written as ordered parts; each row carries a part index that must arrive strictly in sequence per target file. BinaryWriteStrategy.write compares the incoming partIndex against the last recorded index for that output path and throws BINARY_FILE_PART_ORDER_ERROR when partIndex - 1 does not match the stored last index, i.e. a part is missing, duplicated, or out of order.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/sink/writer/BinaryWriteStrategy.java:76

        if (!catalogTable.getSeaTunnelRowType().equals(BinaryReadStrategy.binaryRowType)) {
            throw new FileConnectorException(
                    FileConnectorErrorCode.FORMAT_NOT_SUPPORT,
                    "BinaryWriteStrategy only supports binary format, please read file with `BINARY` format, and do not change schema in the transform.");
        }
    }

    @Override
    public void write(SeaTunnelRow seaTunnelRow) throws FileConnectorException {
        long partIndex = (long) seaTunnelRow.getField(2);
        if (partIndex == -1) {
            return;
        }
        byte[] data = (byte[]) seaTunnelRow.getField(0);
        String relativePath = (String) seaTunnelRow.getField(1);
        String filePath = getOrCreateFilePathBeingWritten(relativePath);
        FSDataOutputStream fsDataOutputStream = getOrCreateOutputStream(filePath);
        if (partIndex - 1 != partIndexMap.get(filePath)) {
            throw new FileConnectorException(
                    FileConnectorErrorCode.BINARY_FILE_PART_ORDER_ERROR,
                    "Last order is " + partIndexMap.get(filePath) + ", but get " + partIndex);
        } else {
            partIndexMap.put(filePath, partIndex);
        }
        try {
            fsDataOutputStream.write(data);
        } catch (IOException e) {
            throw CommonError.fileOperationFailed("BinaryFile", "write", filePath, e);
        }
    }

    public String getOrCreateFilePathBeingWritten(String relativePath) {
        if (fileSinkConfig.isCustomFilename()) {
            return getOrCreateCustomFilePathBeingWritten(relativePath);
        }
        String beingWrittenFilePath = beingWrittenFile.get(relativePath);
        if (beingWrittenFilePath != null) {

View on GitHub (pinned to cf67b549a7)

Solutions

Check the upstream binary source for duplicate or skipped part generation
Ensure the binary stream is not read/written with parallelism that can reorder parts of the same file
Verify the transform chain does not reprocess or replay rows; rebuild the job if replay delivered stale parts

Example fix

null

Defensive patterns

Strategy: try-catch

Validate before calling

// validate incoming binary rows before writing
long expected = lastPartIndexForFile(relativePath) + 1;
if (partIndex != expected) {
  throw new IllegalStateException("Binary part out of order: expected " + expected + " got " + partIndex);
}

Try / catch

try { write(row, partIndex); } catch (FileConnectorException e) {
  if (e.getErrorCode().equals(FileConnectorErrorCode.BINARY_FILE_PART_ORDER_ERROR)) {
    log.error("Binary part stream corrupted for file; abort and re-read source from the beginning", e);
    restartFromSource();
  }
}

Prevention

Ensure the upstream binary producer emits parts strictly sequentially per file
Avoid replaying or reprocessing binary rows after failure without resetting part indices
Do not parallelize writes of parts belonging to the same source file

When it happens

Trigger: Writing a binary row whose part index is not exactly previous_index + 1 for its relativePath — duplicated part index, a skipped part, or parts interleaved out of order from upstream.

Common situations: Upstream source/reader produced duplicate or out-of-order binary parts; parallel writers racing on the same relativePath; data replay after failure re-delivers an old part.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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