chinabugotech/hutool · error · IORuntimeException

Path [{}] is not directory!

Error message

Path [{}] is not directory!

What it means

FileUtil.ls(path) lists the children of a directory. It resolves the path to a File and, if that File is not a directory, throws IORuntimeException("Path [{}] is not directory!"). This is the Hutool guarded equivalent of File.listFiles().

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/io/FileUtil.java:98

	}

	/**
	 * 列出指定路径下的目录和文件<br>
	 * 给定的绝对路径不能是压缩包中的路径
	 *
	 * @param path 目录绝对路径或者相对路径
	 * @return 文件列表（包含目录）
	 */
	public static File[] ls(String path) {
		if (path == null) {
			return null;
		}

		File file = file(path);
		if (file.isDirectory()) {
			return file.listFiles();
		}
		throw new IORuntimeException(StrUtil.format("Path [{}] is not directory!", path));
	}

	/**
	 * 文件是否为空<br>
	 * 目录：里面没有文件时为空 文件：文件大小为0时为空
	 *
	 * @param file 文件
	 * @return 是否为空，当提供非目录时，返回false
	 */
	public static boolean isEmpty(File file) {
		if (null == file || false == file.exists()) {
			return true;
		}

		if (file.isDirectory()) {
			String[] subFiles = file.list();
			return ArrayUtil.isEmpty(subFiles);
		} else if (file.isFile()) {

View on GitHub (pinned to 8870454b2a)

Solutions

1. Check FileUtil.isDirectory(path) before calling ls().
2. If you meant the containing folder, resolve the parent first: FileUtil.file(path).getParentFile().
3. Validate the path comes from a directory chooser/source.

Example fix

// before
File[] children = FileUtil.ls(path); // throws if path is a file

// after
File dir = FileUtil.file(path);
if (dir.isDirectory()) {
    File[] children = FileUtil.ls(path);
} else {
    children = FileUtil.ls(dir.getParent());
}

File dir = FileUtil.file(path);
if (dir != null && dir.isDirectory()) {
    File[] children = FileUtil.ls(path);
} else if (dir != null && dir.isFile()) {
    // user gave a file: list its parent instead
    File[] children = FileUtil.ls(dir.getParent());
}

static boolean isListableDir(String path) {
    if (path == null) return false;
    File f = new File(path);
    return f.exists() && f.isDirectory();
}

try {
    return FileUtil.ls(path);
} catch (IORuntimeException e) {
    // path was not a directory: return empty or rethrow with context
}

When it happens

Trigger: Calling FileUtil.ls(path) where path resolves to a regular file or to a non-existent path (isDirectory() is false for both).

Common situations: User-supplied path that actually points at a file rather than a folder; a config value holding a file path fed to ls(); computing a path relative to a file instead of its parent directory.

Related errors

• Destination Dir must be a Directory !
• Not a regular file!
• Can not read file path of [{}]
• File path is blank!
• File uri is null!

AI-assisted analysis of chinabugotech/hutool@8870454b2a (2026-08-14). Data as JSON: /api/errors/02b70132a3e1773d. Report an issue: GitHub.