What causes "create new file error %s" in lingochamp/FileDownloader?

Verify storage permission is granted and requested at runtime (Android 6.0+ WRITE_EXTERNAL_STORAGE / scoped storage on 10+).

lingochamp/FileDownloader · error · IOException

create new file error

Error message

create new file error  %s

What it means

In createOutputStream, when the destination file does not exist the library calls File.createNewFile(); if that returns false the file could not be created and it throws this IOException naming the absolute path. This typically means the filesystem refused to create the file despite the path not existing.

Solutions

Verify storage permission is granted and requested at runtime (Android 6.0+ WRITE_EXTERNAL_STORAGE / scoped storage on 10+).
Ensure the parent directory exists before downloading: new File(file.getParent()).mkdirs().
Check storage state with Environment.getExternalStorageState() and fall back to internal storage if media is not MOUNTED.
Serialize or deduplicate downloads to the same path so two threads don't race on createNewFile().

Example fix

// before
request.setPath("/sdcard/Download/myfile.apk");
// after
File dir = new File("/sdcard/Download");
if (!dir.exists()) dir.mkdirs();
request.setPath(new File(dir, "myfile.apk").getAbsolutePath());

Defensive patterns

Strategy: try-catch

Validate before calling

File dest = new File(path);
if (!dest.getParentFile().exists()) dest.getParentFile().mkdirs();
if (!Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState())) {
    // use internal storage instead
}

Try / catch

try {
    downloader.create(path);
} catch (IOException e) {
    if (e.getMessage() != null && e.getMessage().contains("create new file error")) {
        // check permissions / storage state, fall back to internal storage
    }
}

Prevention

Request and check storage permissions at runtime before downloading.
Create parent directories with mkdirs() before starting a download.
Check Environment.getExternalStorageState() before using external storage.
Avoid multiple threads creating the same destination file concurrently.

When it happens

Trigger: createOutputStream on a non-existent path where File.createNewFile() returns false — usually because the parent directory doesn't exist, the storage volume is read-only or unmounted, or a file with that name appeared concurrently between the exists() check and createNewFile().

Common situations: Downloading to external storage without WRITE_EXTERNAL_STORAGE permission, targeting removable SD card that was unmounted, parent folder deleted between calls, or concurrent downloads racing on the same path (file created by another thread causing createNewFile to return false).

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 lingochamp/FileDownloader@6237a8cac1 (2026-09-08). Data as JSON: /api/errors/36f1b4ca37db31ff. Report an issue: GitHub.

Appendix: source

Thrown at library/src/main/java/com/liulishuo/filedownloader/util/FileDownloadUtils.java:703

        }

        //noinspection ConstantConditions
        if (!FileDownloadUtils.isFilenameValid(path)) {
            throw new RuntimeException(
                    FileDownloadUtils.formatString("found invalid internal destination filename"
                            + " %s", path));
        }

        File file = new File(path);

        if (file.exists() && file.isDirectory()) {
            throw new RuntimeException(
                    FileDownloadUtils.formatString("found invalid internal destination path[%s],"
                            + " & path is directory[%B]", path, file.isDirectory()));
        }
        if (!file.exists()) {
            if (!file.createNewFile()) {
                throw new IOException(
                        FileDownloadUtils.formatString("create new file error  %s",
                                file.getAbsolutePath()));
            }
        }

        return CustomComponentHolder.getImpl().createOutputStream(file);
    }

    public static boolean isBreakpointAvailable(final int id, final FileDownloadModel model) {
        return isBreakpointAvailable(id, model, null);
    }

    /**
     * @return can resume by break point
     */
    public static boolean isBreakpointAvailable(final int id, final FileDownloadModel model,
                                                final Boolean outputStreamSupportSeek) {
        if (model == null) {

View on GitHub (pinned to 6237a8cac1)