chinabugotech/hutool · error · IllegalArgumentException

图片流是空的

Error message

图片流是空的

What it means

BackgroundRemoval.getMainColor requires a non-null BufferedImage. Passing null throws IllegalArgumentException (message: '图片流是空的' = 'the image stream is empty'). It is a precondition check before iterating pixels.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/img/BackgroundRemoval.java:290

	public static String getMainColor(File input) {
		try {
			return getMainColor(ImageIO.read(input));
		} catch (IOException e) {
			e.printStackTrace();
		}
		return "";
	}

	/**
	 * 获取图片大概的主题色
	 * 循环所有的像素点,取出出现次数最多的一个像素点的RGB值
	 *
	 * @param bufferedImage 图片流
	 * @return 返回一个图片的大概的色值 一个16进制的颜色码
	 */
	public static String getMainColor(BufferedImage bufferedImage) {
		if (bufferedImage == null) {
			throw new IllegalArgumentException("图片流是空的");
		}

		// 存储图片的所有RGB元素
		List<String> list = new ArrayList<>();
		for (int y = bufferedImage.getMinY(); y < bufferedImage.getHeight(); y++) {
			for (int x = bufferedImage.getMinX(); x < bufferedImage.getWidth(); x++) {
				int pixel = bufferedImage.getRGB(x, y);
				list.add(((pixel & 0xff0000) >> 16) + "-" + ((pixel & 0xff00) >> 8) + "-" + (pixel & 0xff));
			}
		}

		final Map<String, Integer> map = new HashMap<>(list.size(), 1);
		for (String string : list) {
			Integer integer = map.get(string);
			if (integer == null) {
				integer = 1;
			} else {
				integer++;

View on GitHub (pinned to 8870454b2a)

Solutions

1. Null-check the BufferedImage before calling getMainColor and handle the load failure at its source.
2. Use ImgUtil.read (File/URL/InputStream) which itself throws a clear error for unsupported types, ensuring a non-null image reaches getMainColor.
3. Validate the source file/URL exists and is a supported image format first.

Example fix

// before
String c = BackgroundRemoval.getMainColor(maybeNullImage);
// after
if (image == null) throw new IllegalStateException("image not loaded");
String c = BackgroundRemoval.getMainColor(image);

void requireImage(BufferedImage img){ if(img==null) throw new IllegalStateException("image not loaded"); }

boolean hasImage(BufferedImage img){ return img != null && img.getWidth() > 0 && img.getHeight() > 0; }

try { c = BackgroundRemoval.getMainColor(img); }
catch (IllegalArgumentException e){ if(e.getMessage().contains("图片流是空的")) { /* reload image */ } else throw e; }

When it happens

Trigger: Calling ImgUtil.wrap/BackgroundRemoval.getMainColor with an image that failed to load (e.g. ImgUtil.read returned null, which it never does because it throws on null, but a user variable may be null); chaining operations where a prior step returned null.

Common situations: Loading an image from an untrusted path/URL that fails; decoding into BufferedImage that ends up null; calling getMainColor before validating the load result.

Related errors

• 给定文件为空
• 文件类型{}不支持
• RGB must be 0~255!
• Destination Dir must be a Directory !
• Image type of file [{}] is not supported!

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