lingochamp/FileDownloader · error · FileDownloadOutOfSpaceException

The file is too large to store, breakpoint in bytes

Error message

The file is too large to store, breakpoint in bytes:  %d, required space in bytes: %d, but free space in bytes: %d

What it means

FileDownloadOutOfSpaceException is thrown in DownloadLaunchRunnable.handlePreAllocate when the free space on the storage device is less than the remaining bytes needed for the download (totalLength minus already-downloaded breakpoint bytes). FileDownloader pre-allocates the file (sets its length to the total size) before writing, so it checks free space up front to fail fast instead of filling the disk.

Solutions

1. Free up storage space on the device (delete files/caches) before retrying
2. Check FileDownloadUtils.getFreeSpaceBytes(path) against the expected content length before starting and skip or alert the user
3. Point the download path at storage with sufficient free space
4. Reduce file size or download in chunks/smaller files
5. Enable FileDownloadProperties.fileNonPreAllocation to skip pre-allocation (does not fix lack of space, but avoids the eager check failing early on filesystems that report sparse space oddly)
6. Catch FileDownloadOutOfSpaceException in onerror and notify the user to free space

Example fix

// before: starting a 2GB download regardless of space
FileDownloader.getImpl().create(url).setPath(path).start();
// after: pre-check free space
long free = FileDownloadUtils.getFreeSpaceBytes(path);
if (free < expectedSizeBytes) {
    // prompt user to free space or choose another directory
} else {
    FileDownloader.getImpl().create(url).setPath(path).start();
}

long free = FileDownloadUtils.getFreeSpaceBytes(path);
long required = expectedTotalBytes - alreadyDownloadedBytes;
if (free < required) {
    // abort or prompt user to free space before starting
    return;
}

try {
    FileDownloader.getImpl().create(url).setPath(path).start(listener);
} catch (FileDownloadOutOfSpaceException e) {
    // e.getFreeSpaceBytes(), e.getRequiredSpaceBytes()
    showFreeSpaceDialog();
}

When it happens

Trigger: Downloading a file whose total length exceeds available free space on the target path's volume; also triggered whenever pre-allocation is enabled (default) and free space < totalLength - breakpointBytes.

Common situations: Large video/APK downloads on devices with nearly full internal storage; downloading to an SD card that is full or almost full; resuming a large download where the device filled up in the meantime; misreporting free space when path is on a different volume than expected.

Related errors

• response code error: , request headers: response headers
• the download runnable must not be null!
• Task[ ] can't start the download runnable, because this…
• Connection failed with request
• If you start the task manually, it means this task doesn't…

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

Appendix: source

Thrown at library/src/main/java/com/liulishuo/filedownloader/download/DownloadLaunchRunnable.java:775

        }
    }

    private void handlePreAllocate(long totalLength, String path)
            throws IOException, IllegalAccessException {

        FileDownloadOutputStream outputStream = null;
        try {

            if (totalLength != TOTAL_VALUE_IN_CHUNKED_RESOURCE) {
                outputStream = FileDownloadUtils.createOutputStream(model.getTempFilePath());
                final long breakpointBytes = new File(path).length();
                final long requiredSpaceBytes = totalLength - breakpointBytes;

                final long freeSpaceBytes = FileDownloadUtils.getFreeSpaceBytes(path);

                if (freeSpaceBytes < requiredSpaceBytes) {
                    // throw a out of space exception.
                    throw new FileDownloadOutOfSpaceException(freeSpaceBytes,
                            requiredSpaceBytes, breakpointBytes);
                } else if (!FileDownloadProperties.getImpl().fileNonPreAllocation) {
                    // pre allocate.
                    outputStream.setLength(totalLength);
                }
            }
        } finally {
            if (outputStream != null) outputStream.close();
        }
    }

    private long lastCallbackBytes = 0;
    private long lastCallbackTimestamp = 0;

    private long lastUpdateBytes = 0;
    private long lastUpdateTimestamp = 0;

    @Override

View on GitHub (pinned to 6237a8cac1)