lingochamp/FileDownloader · error · IOException

Can't rename the temp downloaded file

Error message

Can't rename the  temp downloaded file(%s) to the target file(%s)

What it means

Thrown by DownloadStatusCallback.renameTempFile (called from handleCompleted) when File.renameTo from the temp path (.tmp) to the final target path returns false after the download completed. The rename is atomic on most filesystems but fails when paths are on different mount points, the target directory is missing, or permissions are insufficient — leaving the fully downloaded data unusable until finalized.

Solutions

1. Make sure the temp file and target file are on the same filesystem/volume and the target directory exists.
2. Check and fix write permissions on the target directory.
3. Manually copy the temp file to the target path as a fallback, then delete the temp file.
4. Catch the IOException in the download error callback and retry the task after cleaning up leftover temp/target files.

When it happens

Trigger: Thrown at library/src/main/java/com/liulishuo/filedownloader/download/DownloadStatusCallback.java:316 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of lingochamp/FileDownloader@6237a8cac1 (2026-09-08). Data as JSON: /api/errors/c6b9985fbc7e7350. Report an issue: GitHub.

Appendix: source

Thrown at library/src/main/java/com/liulishuo/filedownloader/download/DownloadStatusCallback.java:316

            if (targetFile.exists()) {
                final long oldTargetFileLength = targetFile.length();
                if (!targetFile.delete()) {
                    throw new IOException(FileDownloadUtils.formatString(
                            "Can't delete the old file([%s], [%d]), "
                                    + "so can't replace it with the new downloaded one.",
                            targetPath, oldTargetFileLength
                    ));
                } else {
                    FileDownloadLog.w(this, "The target file([%s], [%d]) will be replaced with"
                                    + " the new downloaded file[%d]",
                            targetPath, oldTargetFileLength, tempFile.length());
                }
            }

            renameFailed = !tempFile.renameTo(targetFile);
            if (renameFailed) {
                throw new IOException(FileDownloadUtils.formatString(
                        "Can't rename the  temp downloaded file(%s) to the target file(%s)",
                        tempPath, targetPath
                ));
            }
        } finally {
            if (renameFailed && tempFile.exists()) {
                if (!tempFile.delete()) {
                    FileDownloadLog.w(this,
                            "delete the temp file(%s) failed, on completed downloading.",
                            tempPath);
                }
            }
        }
    }

    @Override
    public boolean handleMessage(Message msg) {
        handlingMessage = true;

View on GitHub (pinned to 6237a8cac1)