Post-sync backup failed: backup target path is empty, splitI

Error message

Post-sync backup failed: backup target path is empty, splitId={}, source={}

What it means

This WARN is emitted by the file source split enumerator when a post-sync backup operation reaches checkpoint commit but the operation state carries a blank backupTargetPath. Without a destination the backup rename cannot proceed, so the enumerator returns FAILED_RETRYABLE and the operation is retried at the next checkpoint. It indicates the operation was registered without a backup path being resolved.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/split/ContinuousMultipleTableFileSourceSplitEnumerator.java:823

        }
    }

    private static String sha256Hex(byte[] bytes) {
        char[] digits = "0123456789abcdef".toCharArray();
        char[] encoded = new char[bytes.length * 2];
        for (int i = 0; i < bytes.length; i++) {
            int current = bytes[i] & 0xff;
            encoded[i * 2] = digits[current >>> 4];
            encoded[i * 2 + 1] = digits[current & 0x0f];
        }
        return new String(encoded);
    }

    private OpCommitResult commitBackupOperation(
            TableScanContext ctx, FileSourceOperationState op, long checkpointId)
            throws IOException {
        if (StringUtils.isBlank(op.getBackupTargetPath())) {
            log.warn(
                    "Post-sync backup failed: backup target path is empty, splitId={}, source={}",
                    op.getSplitId(),
                    maskUriUserInfo(op.getSourcePath()));
            return OpCommitResult.FAILED_RETRYABLE;
        }

        String stagingPath = buildBackupStagingPath(op);
        FileStatus sourceStatus = getFileStatusIfPresent(ctx.sourceFs, op.getSourcePath());
        FileStatus targetStatus = getFileStatusIfPresent(ctx.sourceFs, op.getBackupTargetPath());
        FileStatus stagingStatus = getFileStatusIfPresent(ctx.sourceFs, stagingPath);

        if (sourceStatus == null) {
            if (targetStatus != null) {
                if (isOperationContentMatched(ctx, op, op.getBackupTargetPath(), targetStatus)) {
                    log.info(
                            "Post-sync backup completed during a previous attempt: source={}, target={}, "
                                    + "checkpointId={}, capturedLen={}, capturedMtime={}",
                            maskUriUserInfo(op.getSourcePath()),

View on GitHub (pinned to cf67b549a7)

Solutions

Set the backup target path option correctly in the file source config so every backup operation gets a non-blank destination
Check how FileSourceOperationState was serialized/restored from checkpoint/operator state; ensure the backupTargetPath field is populated on restore
Inspect upstream code that builds the backup target path (path resolution/templating) for empty-string results
Verify the connector version matches between checkpoint savepoint and the running job

Example fix

// before
backup-path = 
// after
backup-path = hdfs:///warehouse/backup/${table}

Defensive patterns

Strategy: validation

Validate before calling

// Before registering/committing a backup operation, assert the target path is set
if (op.getBackupTargetPath() == null || op.getBackupTargetPath().isBlank()) {
    throw new IllegalArgumentException(
        "backupTargetPath must be resolved before committing backup op " + op.getSplitId());
}

Type guard

boolean hasBackupTarget(FileSourceOperationState op) {
    return op != null && op.getBackupTargetPath() != null && !op.getBackupTargetPath().isBlank();
}

Prevention

Always configure the backup target path option; validate non-empty at job-configuration parse time
Unit-test the code path that builds FileSourceOperationState to assert backupTargetPath is populated
When upgrading connector versions, validate restored operator state for new required fields

When it happens

Trigger: A FileSourceOperationState for action=backup was created with an unset/blank backup target path (e.g. backup configuration missing or path resolution failed upstream) and commitBackupOperation() runs during checkpoint commit.

Common situations: Misconfigured backup/backup-path option so the target is never populated; an operator state written by an older connector version that predates the backup-target field being restored into a newer job; a bug in path resolution returning empty string.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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