Post-sync {}: failed to restore staged file after stale-cont

Error message

Post-sync {}: failed to restore staged file after stale-content detection; operation will be retried: source={}, staging={}, checkpointId={}

What it means

This WARN/ERROR pair comes from handleStaleStagedOperation(): when a staged file's content does not match the captured version (stale), the enumerator tries to restore it to the source path. This specific error line fires when the restore itself fails, so neither the source nor a valid backup exists in a consistent place; the operation returns FAILED_RETRYABLE. It is logged via log.error despite the message text shown at this call site family — treat it as the highest-priority condition in this flow.

Source

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

            FileSourceOperationState op,
            long checkpointId,
            String stagedPath,
            String actionLabel,
            FileStatus stagedStatus)
            throws IOException {
        RestoreStagedFileResult restoreResult =
                restoreStagedSource(ctx, op, stagedPath, stagedStatus, actionLabel);
        if (restoreResult == RestoreStagedFileResult.FAILED) {
            log.error(
                    "Post-sync {}: failed to restore staged file after stale-content detection; "
                            + "operation will be retried: source={}, staging={}, checkpointId={}",
                    actionLabel,
                    maskUriUserInfo(op.getSourcePath()),
                    maskUriUserInfo(stagedPath),
                    checkpointId);
            return OpCommitResult.FAILED_RETRYABLE;
        }
        log.warn(
                "Post-sync {} skipped due to stale staged content: splitId={}, source={}, staging={}, "
                        + "checkpointId={}",
                actionLabel,
                op.getSplitId(),
                maskUriUserInfo(op.getSourcePath()),
                maskUriUserInfo(stagedPath),
                checkpointId);
        return OpCommitResult.STALE_SKIPPED;
    }

    private OpCommitResult handleRetryableStagedOperation(
            TableScanContext ctx,
            FileSourceOperationState op,
            long checkpointId,
            String stagedPath,
            String actionLabel,
            FileStatus stagedStatus)
            throws IOException {

View on GitHub (pinned to cf67b549a7)

Solutions

Inspect the surrounding log lines for the restore failure cause (target exists, permission, IO error)
If the source path was recreated by a new writer, decide manually which version is authoritative and clean up the stale staged file
Fix directory permissions so the restore rename into the source directory can succeed
If the stale staged file is garbage from an old attempt, delete it and clear/let expire the operation state

Example fix

null

Defensive patterns

Strategy: retry

Validate before calling

// Before restoring a staged file, confirm the source path is not occupied by a newer version:
FileStatus s = fs.getFileStatusIfPresent(sourcePath);
if (s != null && s.getModificationTime() > op.getSourceModificationTime()) {
    // source was recreated; do not blind-overwrite — route to manual resolution
}

Try / catch

try {
    restoreStagedToSource(stagedPath, sourcePath);
} catch (IOException e) {
    // alert: data exists only in staging; bounded retry then operator intervention
}

Prevention

Prevent concurrent writers from recreating source paths during post-sync operations
Fix source-directory permissions ahead of time
Treat restore-failure logs as high priority — the only live copy is the staged file

When it happens

Trigger: isOperationContentMatched() fails on the staged file (stale content), restoreStagedSource() attempts to move/restore the staged file back to op.getSourcePath(), and that restore returns RestoreStagedFileResult.FAILED.

Common situations: Source path already recreated by a concurrent writer so the restore cannot overwrite it; permission errors on the source directory; transient FS failure mid-restore; stale staged file left from a much older attempt whose source version no longer exists.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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