apache/seatunnel · critical · CheckpointStorageException
Failed to rename tmp file to final file
Error message
Failed to rename tmp file to final file
What it means
After writing the tmp checkpoint file, storeCheckPoint renames it to the final path. If fs.rename returns false (no exception but rename not performed) the method throws this CheckpointStorageException. The tmp file is then deleted in the finally block. This is the 'silent failure' variant of the rename error, where Hadoop simply reports the rename did not happen.
Source
Thrown at seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-hdfs/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/hdfs/HdfsStorage.java:120
new Path(
getStorageParentDirectory()
+ state.getJobId()
+ "/"
+ getCheckPointName(state)
+ STORAGE_TMP_SUFFIX);
try (FSDataOutputStream out = fs.create(tmpFilePath, false)) {
out.write(datas);
} catch (IOException e) {
throw new CheckpointStorageException(
String.format(
"Failed to write checkpoint data, file: %s, state: %s",
tmpFilePath, state),
e);
}
try {
boolean success = fs.rename(tmpFilePath, filePath);
if (!success) {
throw new CheckpointStorageException("Failed to rename tmp file to final file");
}
} catch (IOException e) {
throw new CheckpointStorageException("Failed to rename tmp file to final file");
} finally {
try {
// clean up tmp file, if still lying around
if (fs.exists(tmpFilePath)) {
fs.delete(tmpFilePath, false);
}
} catch (IOException ioe) {
log.error("Failed to delete tmp file", ioe);
}
}
return filePath.getName();
}
View on GitHub (pinned to cf67b549a7)
Solutions
- Verify the checkpoint parent directory exists and is writable (hdfs dfs -mkdir -p; hdfs dfs -chmod)
- Check the nested finally-cleanup logs to confirm the tmp file existed before rename
- Prevent duplicate jobIds / concurrent writers racing on the same checkpoint path
- Check HDFS permissions on both source and target paths (rename needs write on both dirs)
- Inspect NameNode logs around the failure time for the specific rename denial reason
Example fix
// before
// assume parent dir exists
// after
if (!fs.exists(parentDir)) { fs.mkdirs(parentDir); }
boolean success = fs.rename(tmpFilePath, filePath); Defensive patterns
Strategy: try-catch
Validate before calling
// pre-flight: ensure destination parent exists and is writable if (!fs.exists(parentDir)) fs.mkdirs(parentDir); FsPermission perm = fs.getFileStatus(parentDir).getPermission(); // verify action write access for the submitting user
Try / catch
try {
storage.storeCheckPoint(state);
} catch (CheckpointStorageException e) {
if (e.getMessage().equals("Failed to rename tmp file to final file")) {
log.error("Rename returned false: check parent dir existence, permissions, and concurrent writers");
} else throw e;
} Prevention
- Create the checkpoint parent directory before job submission and never delete it while jobs run
- Ensure only one writer uses a given jobId/checkpoint path
- Verify write permission on BOTH source and destination directories (rename requires both)
- Check NameNode logs when rename silently fails — the exception carries no cause
When it happens
Trigger: storeCheckPoint (also via modifyResumeTokenInCheckpoint) when fs.rename(tmpFilePath, filePath) returns false — typically because the target parent directory does not exist, the target already exists and is a directory, or the source tmp file vanished (deleted by another process/concurrent writer).
Common situations: Checkpoint parent directory removed or never created on HDFS, two writers with the same jobId racing, tmp file already cleaned by a retention/cleanup job, or HDFS permission allowing write of new files but not rename operations in the target dir.
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
- Failed to get file system
- Failed to serialize checkpoint data, state: ${state}
- Failed to write checkpoint data, file: ${tmpFilePath}, state
- No checkpoint found for job, job id is: ${jobId}
- FILE_LIST_GET_FAILED
AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10).
Data as JSON: /api/errors/2aff9abd821c4156.
Report an issue: GitHub.