Fallback content comparison failed, fallback to COPY. source

Error message

Fallback content comparison failed, fallback to COPY. source={}, target={}

What it means

Warning logged when even the fallback content comparison (byte-stream equality check after checksums were unavailable) throws an Exception. To stay safe, the reader returns true (files treated as different) and falls back to performing a full COPY of the file.

Source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/reader/AbstractReadStrategy.java:981

                            log.warn(
                                    "File checksum is not available, fallback to content comparison. source={}, target={}",
                                    maskUriUserInfo(sourceFilePath),
                                    maskUriUserInfo(targetFilePath),
                                    checksumException);
                        }
                        checksumUnavailableWarned = true;
                    }
                    try {
                        boolean sameContent = fileContentEquals(sourceFilePath, targetFilePath);
                        if (sameContent) {
                            logUpdateModeSkip(
                                    sourceFilePath,
                                    targetFilePath,
                                    "strict checksum: content equal (checksum unavailable)");
                        }
                        return !sameContent;
                    } catch (Exception e) {
                        log.warn(
                                "Fallback content comparison failed, fallback to COPY. source={}, target={}",
                                maskUriUserInfo(sourceFilePath),
                                maskUriUserInfo(targetFilePath),
                                e);
                        return true;
                    }
                }
                if (checksumEquals(sourceChecksum, targetChecksum)) {
                    logUpdateModeSkip(
                            sourceFilePath, targetFilePath, "strict checksum: checksum equal");
                    return false;
                }
                return true;
            }
        }

        return true;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

Check the logged exception; fix the underlying read problem (permissions, connectivity, concurrent writes).
Re-run the sync job — the fallback already re-copied the file, so subsequent runs may compare cleanly.
Avoid mutating source files while a sync job is running (freeze writes or snapshot first).
If content comparison keeps failing on large files, disable strict checksum mode to skip the comparison path.

Defensive patterns

Strategy: retry

Validate before calling

// pre-check readability of both files before comparison
fs.open(srcPath).close();
targetFs.open(dstPath).close();

Try / catch

try {
    boolean same = contentEquals(src, dst);
    return !same;
} catch (Exception e) {
    log.warn("content comparison failed, copying anyway", e);
    return true; // safe default: full copy
}

Prevention

Ensure read permissions on both source and target before sync.
Avoid concurrent writes to files being compared.
Re-run sync after a comparison failure — the fallback copy already re-synchronized the file.

When it happens

Trigger: During strict checksum sync mode: checksums unavailable → content comparison via stream reading fails — read permission errors, file deleted/modified mid-comparison, or network I/O errors while streaming either file.

Common situations: Files being rewritten concurrently by another writer during sync; missing read permissions on target; transient HDFS/S3 read failures; very large files timing out mid-stream.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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