apache/seatunnel · warning

Post-sync backup: rename-to-staging failed, will retry: sour

Error message

Post-sync backup: rename-to-staging failed, will retry: source={}, staging={}

What it means

This WARN is emitted when renaming the source file to the backup staging path fails with an exception during commitBackupOperation(). The rename is the first mutation of the backup flow; when it throws (IO error, permission issue, cross-device move, transient FS failure) the enumerator logs the exception and returns FAILED_RETRYABLE so the next checkpoint attempt redoes it.

Source

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

                    checkpointId);
            return OpCommitResult.STALE_SKIPPED;
        }

        if (sourceStatus != null
                && stagingStatus == null
                && !isSinkTargetCommitted(ctx, op, checkpointId, op.getSourcePath())) {
            // Keep the source visible until the sink target reaches its final committed location.
            // This avoids unnecessary source-side rename/restore churn on file systems such as FTP
            // where a staged move can temporarily hide the discovery root before the sink commit is
            // actually durable.
            return OpCommitResult.FAILED_RETRYABLE;
        }

        if (stagingStatus == null) {
            try {
                ctx.sourceFs.renameFile(op.getSourcePath(), stagingPath, false);
            } catch (Exception e) {
                log.warn(
                        "Post-sync backup: rename-to-staging failed, will retry: source={}, staging={}",
                        maskUriUserInfo(op.getSourcePath()),
                        maskUriUserInfo(stagingPath),
                        e);
                return OpCommitResult.FAILED_RETRYABLE;
            }
            stagingStatus = getFileStatusIfPresent(ctx.sourceFs, stagingPath);
        }

        if (stagingStatus == null) {
            log.warn(
                    "Post-sync backup staging disappeared before verification; operation will be retried: "
                            + "splitId={}, source={}, staging={}, checkpointId={}",
                    op.getSplitId(),
                    maskUriUserInfo(op.getSourcePath()),
                    maskUriUserInfo(stagingPath),
                    checkpointId);
            return OpCommitResult.FAILED_RETRYABLE;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the stacked exception in the log — it names the real cause (permission, NoSuchFile, throttling, timeout)
2. Verify the connector identity has write permission on both the source directory and the staging/backup parent directories
3. Ensure the staging parent directory exists and is on the same filesystem/device as the source (rename across filesystems is not atomic)
4. Check object-store rate limits and retry/backoff settings if using S3/OSS; retry the checkpoint commit

Example fix

// before (FTP user without write access on staging dir)
# FTP: 550 Permission denied
// after
# grant write on the staging directory to the job user
site chmod 775 /backup/staging

// Pre-flight: confirm write access on source and staging directories before starting the job
Path stagingDir = new Path(stagingPath).getParent();
if (!fs.exists(stagingDir)) { fs.mkdirs(stagingDir); }
FSDataOutputStream probe = fs.create(new Path(stagingDir, ".write-probe"));
probe.close(); fs.delete(new Path(stagingDir, ".write-probe"), false);

try {
    fs.renameFile(source, staging, false);
} catch (IOException e) {
    // inspect e: permission, FileNotFoundException, throttling; backoff and retry
    Thread.sleep(backoffMs); retry();
}

When it happens

Trigger: ctx.sourceFs.renameFile(op.getSourcePath(), stagingPath, false) throws — e.g. permission denied on source or staging directory, staging directory missing, transient HDFS/S3/network error, or source file locked/being written concurrently.

Common situations: Insufficient HDFS/FTP/S3 permissions on the staging directory; staging parent directory not created; object-store throttling (S3 503 slow-down); network partition between the JobManager and the filesystem; another process holding/renaming the same source file.

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

• Post-sync operation cannot verify sink target and will be re
• Post-sync backup failed: backup target path is empty, splitI
• Post-sync backup cannot determine completion because source,
• Post-sync backup staging disappeared before verification; op
• Post-sync backup promotion target is absent after rename; op

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