alibaba/spring-ai-alibaba · warning · IllegalStateException

Utility class

Error message

Utility class

What it means

FileUtils is a static utility class whose private constructor deliberately throws this IllegalStateException to prevent instantiation via reflection or accidental new FileUtils(). It is an intentional guard, not a bug in the library.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/utils/FileUtils.java:31

 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.alibaba.cloud.ai.graph.utils;

import java.io.IOException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;

/**
 * @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. Use the static methods directly: FileUtils.writeCodeToFile(...), FileUtils.copyResourceJarToWorkDir(...).
2. Never instantiate utility classes; call them statically.
3. If a framework insists on instantiation, register the class as excluded or make members static-accessed only.

Example fix

// before
FileUtils fu = new FileUtils(); // throws
fu.writeCodeToFile(dir, name, code);
// after
FileUtils.writeCodeToFile(dir, name, code);

static boolean isUtilityClass(Class<?> c) {
    return java.lang.reflect.Modifier.isPublic(c.getModifiers())
        && c.getDeclaredConstructors().length == 1
        && java.lang.reflect.Modifier.isPrivate(c.getDeclaredConstructors()[0].getModifiers());
}

try {
    Constructor<FileUtils> c = FileUtils.class.getDeclaredConstructor();
    c.setAccessible(true);
    c.newInstance();
} catch (InvocationTargetException e) {
    // expected: IllegalStateException "Utility class" — use static methods instead
}

When it happens

Trigger: Any attempt to instantiate the class: new FileUtils(), or reflective instantiation (Class.newInstance / ReflectionUtils) — e.g. frameworks or serializers that try to construct every class on the classpath.

Common situations: Java reflection-based tools, code-coverage/serialization frameworks instantiating utility classes, or a developer newing up the class by habit.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 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/9e557b7b9644a7f1. Report an issue: GitHub.