lingochamp/FileDownloader · error · IllegalStateException

can't generate real path, the file name is null

Error message

can't generate real path, the file name is null

What it means

generateFilePath builds the absolute save path as <directory>/<filename>. A null filename cannot produce a valid path, so the library fails fast with an IllegalStateException instead of returning a broken path. It is thrown before the directory check, so the filename is the first thing validated.

Solutions

1. Provide a filename: call task.setPath(...) or pass a non-null filename to generateFilePath.
2. If the filename comes from the server, ensure the response includes Content-Disposition or that generateFileName(url) can derive one from the URL.
3. Guard the call site: if (filename != null) generateFilePath(directory, filename) else fall back to generateFileName(url).

Example fix

// before
String path = FileDownloadUtils.generateFilePath(dir, task.getFilename()); // getFilename() == null

// after
String filename = task.getFilename() != null ? task.getFilename() : FileDownloadUtils.generateFileName(url);
String path = FileDownloadUtils.generateFilePath(dir, filename);

if (filename == null) {
    filename = FileDownloadUtils.generateFileName(url);
}
String path = FileDownloadUtils.generateFilePath(directory, filename);

boolean hasFilename(String f) { return f != null && !f.trim().isEmpty(); }

try {
    return FileDownloadUtils.generateFilePath(directory, filename);
} catch (IllegalStateException e) {
    return FileDownloadUtils.generateFilePath(directory, FileDownloadUtils.generateFileName(url));
}

When it happens

Trigger: Calling FileDownloadUtils.generateFilePath(directory, null), directly or via getDefaultSaveFilePath when the task/connection yields no filename.

Common situations: Passing a task whose filename was never set (no FileDownloadTask.path(...) and server response lacks Content-Disposition so filename inference fails); calling the util directly with an uninitialized variable.

Related errors

• can't generate real path, the directory is null
• listener must not be null!
• event must not be null!
• connection is null when findEtag
• create FileDownloadQueueSet must with valid target!

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

Appendix: source

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

        } else {
            return FileDownloadHelper.getAppContext().getCacheDir().getAbsolutePath();
        }
    }

    public static String getDefaultSaveFilePath(final String url) {
        return generateFilePath(getDefaultSaveRootPath(), generateFileName(url));
    }

    public static String generateFileName(final String url) {
        return md5(url);
    }

    /**
     * @see #getTargetFilePath(String, boolean, String)
     */
    public static String generateFilePath(String directory, String filename) {
        if (filename == null) {
            throw new IllegalStateException("can't generate real path, the file name is null");
        }

        if (directory == null) {
            throw new IllegalStateException("can't generate real path, the directory is null");
        }

        return formatString("%s%s%s", directory, File.separator, filename);
    }

    /**
     * The path is used as the default directory in the case of the task without set path.
     *
     * @param path default root path for save download file.
     * @see com.liulishuo.filedownloader.BaseDownloadTask#setPath(String, boolean)
     */
    public static void setDefaultSaveRootPath(final String path) {
        defaultSaveRootPath = path;
    }

View on GitHub (pinned to 6237a8cac1)