chinabugotech/hutool · error · IllegalArgumentException

Not a regular file!

Error message

Not a regular file!

What it means

FileTypeUtil.getType(File, boolean) detects a file's type from its magic header bytes. It rejects anything that is not a regular file — directories, missing paths, special device files — with IllegalArgumentException, because reading header bytes from them is meaningless.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/io/FileTypeUtil.java:210

	}

	/**
	 * 根据文件流的头部信息获得文件类型
	 *
	 * <pre>
	 *     1、无法识别类型默认按照扩展名识别
	 *     2、xls、doc、msi头信息无法区分，按照扩展名区分
	 *     3、zip可能为jar、war头信息无法区分，按照扩展名区分
	 * </pre>
	 *
	 * @param file    文件 {@link File}
	 * @param isExact 是否精确匹配，如果为false，使用前64个bytes匹配，如果为true，使用前8192bytes匹配
	 * @return 类型，文件的扩展名，未找到为{@code null}
	 * @throws IORuntimeException 读取文件引起的异常
	 */
	public static String getType(File file, boolean isExact) throws IORuntimeException {
		if (false == FileUtil.isFile(file)) {
			throw new IllegalArgumentException("Not a regular file!");
		}
		FileInputStream in = null;
		try {
			in = IoUtil.toStream(file);
			return getType(in, file.getName(), isExact);
		} finally {
			IoUtil.close(in);
		}
	}

	/**
	 * 根据文件流的头部信息获得文件类型
	 *
	 * <pre>
	 *     1、无法识别类型默认按照扩展名识别
	 *     2、xls、doc、msi头信息无法区分，按照扩展名区分
	 *     3、zip可能为jar、war头信息无法区分，按照扩展名区分
	 * </pre>

View on GitHub (pinned to 8870454b2a)

Solutions

1. Guard with FileUtil.isFile(file) (exists && not a directory) before calling getType.
2. Filter directory listings to regular files before type detection.
3. Confirm the file exists and is readable at the point of call.

Example fix

// before
String type = FileTypeUtil.getType(file); // -> IllegalArgumentException if dir/missing

// after
if (FileUtil.isFile(file)) {
    String type = FileTypeUtil.getType(file);
}

if (FileUtil.isFile(file)) {
    String type = FileTypeUtil.getType(file, isExact);
} else {
    // skip or report: directory / missing / special file
}

static boolean isDetectableFile(File f) {
    return f != null && f.isFile();
}

try {
    return FileTypeUtil.getType(file);
} catch (IllegalArgumentException e) {
    // not a regular file: handle missing/dir case
}

When it happens

Trigger: Passing a directory, a non-existent File, or a special/device File to FileTypeUtil.getType(File, boolean) or the single-arg getType(File).

Common situations: Iterating a directory's entries and calling getType on every child including subdirectories; resolving a path from user input that does not exist yet; pointing at a symlink whose target is a folder.

Related errors

• File path is blank!
• Input must be a File
• File not exist: {}
• Can't compare directories, only files
• File not exist: {}

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