alibaba/spring-ai-alibaba · error · ClassNotFoundException

Unsupported array type representation: {}

Error message

Unsupported array type representation: {}

What it means

resolveArrayClass only understands JVM-style names starting with '[' (e.g. '[Ljava.lang.String;') and source-style names ending with '[]' (e.g. 'String[]', 'int[]'). Any other representation is rejected by throwing ClassNotFoundException with this message.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/serializer/plain_text/jackson/JacksonDeserializer.java:521

	 * @throws IOException if binding fails
	 */
	private static Object instantiateScalarPayloadArray(String className, JsonNode payload, ObjectMapper objectMapper)
			throws IOException {
		try {
			Class<?> arrayClass = resolveArrayClass(className);
			return objectMapper.treeToValue(payload, arrayClass);
		}
		catch (ClassNotFoundException | IllegalArgumentException ex) {
			throw new IOException("Cannot instantiate array type from scalar payload: " + className, ex);
		}
	}

	private static Class<?> resolveArrayClass(String className) throws ClassNotFoundException {
		if (className.startsWith("[")) {
			return Class.forName(className);
		}
		if (!className.endsWith("[]")) {
			throw new ClassNotFoundException("Unsupported array type representation: " + className);
		}
		String componentName = className.substring(0, className.length() - 2);
		return switch (componentName) {
			case "boolean" -> boolean[].class;
			case "byte" -> byte[].class;
			case "char" -> char[].class;
			case "short" -> short[].class;
			case "int" -> int[].class;
			case "long" -> long[].class;
			case "float" -> float[].class;
			case "double" -> double[].class;
			default -> Class.forName("[L" + componentName + ";");
		};
	}

	/**
	 * Reconstruct GraphResponse from snapshot map.
	 */

View on GitHub (pinned to f82da0b50f)

Solutions

1. Fix the serialized type id to a supported form: JVM descriptor ('[I') or suffix form ('int[]')
2. If you control serialization, ensure default typing records the full array class name, not the component name
3. For primitives use the exact 'primitive[]' spelling: byte[], int[], boolean[], char[], etc.
4. Locate the producer of the malformed class name (custom serializer or external tool) and correct it

Example fix

// before
{"type":"byte"}
// after
{"type":"byte[]"}

boolean valid = className.startsWith("[") || className.endsWith("[]");

boolean isSupportedArrayName(String className) {
    return className != null && (className.startsWith("[") || className.endsWith("[]"));
}

try { Class<?> c = resolveArrayClass(name); } catch (ClassNotFoundException e) { if (e.getMessage().startsWith("Unsupported array type representation")) { name = normalizeToArrayName(name); } else throw e; }

When it happens

Trigger: arrayClass/resolveArrayClass receives a className that neither starts with '[' nor ends with '[]' — e.g. 'byte', 'java.lang.String', '[B[]x' typos, or a null/aliased type id written by a custom serializer.

Common situations: Custom TypeSerializer writing a bare component type name instead of an array name; migration from another serialization format; hand-edited checkpoint files.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Cannot instantiate array type: {}
• Could not find executeAgent method in AgentToolExecutor clas
• Status value cannot be null
• Unknown status: ${value}. Valid values are: pending, in_prog
• Unable to load checkpoints

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