alibaba/spring-ai-alibaba · warning · IllegalStateException

Utility class

Error message

Utility class

What it means

FileUtils is a static utility class whose private constructor throws IllegalStateException("Utility class") if instantiated. This is an intentional anti-instantiation guard, not a runtime failure path — hitting it means reflection, accidental subclassing, or deserialization tried to create a FileUtils instance.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/utils/FileUtils.java:37

import java.io.IOException;
import java.net.URI;
import java.net.URL;
import java.nio.file.FileSystem;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.Collections;
import java.util.Enumeration;

/**
 * @author HeYQ
 * @since 2024-11-28 11:47
 */
public class FileUtils {

	private FileUtils() {
		throw new IllegalStateException("Utility class");
	}

	public static void writeCodeToFile(String workDir, String filename, String code) {
		try {
			if (code == null) {
				throw new IllegalArgumentException("Code must not be null");
			}
			Path filepath = Path.of(workDir, filename);
			// ensure the parent directory exists
			Path fileDir = filepath.getParent();
			if (fileDir != null && !Files.exists(fileDir)) {
				Files.createDirectories(fileDir);
			}
			// write the code to the file
			Files.writeString(filepath, code);
		}
		catch (IOException e) {
			throw new RuntimeException(e);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Remove the instantiation and call the static methods directly: FileUtils.writeCodeToFile(...).
2. If a framework requires an instance, wrap the static calls in your own injectable service class.
3. Suppress framework scanning of this class rather than bypassing the guard.

Example fix

// before
FileUtils fu = new FileUtils(); // IllegalStateException
fu.writeCodeToFile(workDir, filename, code);
// after
FileUtils.writeCodeToFile(workDir, filename, code); // static call

// never instantiate utilities; call statically
boolean ok = FileUtils.class != null; // use FileUtils.writeCodeToFile(...) directly

static void writeCode(String workDir, String filename, String code) {
    FileUtils.writeCodeToFile(workDir, filename, code); // static access, no instantiation
}

try {
    FileUtils.class.getDeclaredConstructor().setAccessible(true);
    // avoid this entirely — FileUtils is non-instantiable by design
} catch (Exception e) {
    // expected: use static methods instead
}

When it happens

Trigger: Calling new FileUtils() (compile error normally, but reachable via reflection), Class.newInstance, some serialization frameworks, or mocking frameworks instantiating the class.

Common situations: Mistakenly writing 'new FileUtils()' by habit; reflection-based frameworks (certain JSON serializers or DI tools) probing constructors; code coverage tooling instantiating private constructors.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Utility class
• Utility class cannot be instantiated
• Could not find executeAgent method in AgentToolExecutor clas
• Cannot instantiate array type: {}
• Unsupported array type representation: {}

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/b41a67f07f941b7f. Report an issue: GitHub.