lingochamp/FileDownloader · error · IllegalStateException

can't generate real path, the directory is null

Error message

can't generate real path, the directory is null

What it means

generateFilePath requires a non-null directory to compose '<directory><separator><filename>'. A null directory means the target storage location is unknown, so the library throws IllegalStateException rather than writing to an unpredictable location.

Solutions

1. Pass a valid directory, e.g. FileDownloadUtils.getDefaultSaveDirectory() or context.getExternalFilesDir(null).getAbsolutePath().
2. Initialize the default download directory (FileDownloadUtils.setDefaultSaveRootPath or let the library set it up with an app context) before generating paths.
3. Null-check the directory at the call site and fall back to the default save directory.

Example fix

// before
String path = FileDownloadUtils.generateFilePath(null, "file.zip");

// after
String dir = customDir != null ? customDir : FileDownloadUtils.getDefaultSaveDirectory();
String path = FileDownloadUtils.generateFilePath(dir, "file.zip");

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

boolean hasDirectory(String d) { return d != null && new File(d).isDirectory(); }

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

When it happens

Trigger: Calling FileDownloadUtils.generateFilePath(null, filename), or getDefaultSaveFilePath with a null directory (e.g. FileDownloadUtils.getDefaultSaveDirectory() returned null because the custom save directory was never initialized).

Common situations: Using a custom download directory before FileDownloader.setupOnWriteOver() / context is ready; passing the result of a method that returns null when external storage path resolution fails; unit tests calling the util with a stubbed directory.

Related errors

• can't generate real path, the file name 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/5c2972190aa49e9d. Report an issue: GitHub.

Appendix: source

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

    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;
    }

    /**
     * @param targetPath The target path for the download task.
     * @return The temp path is {@code targetPath} in downloading status; The temp path is used for

View on GitHub (pinned to 6237a8cac1)