alibaba/spring-ai-alibaba · error · IllegalArgumentException

invalid dsl

Error message

invalid dsl

What it means

Thrown by CustomDSLAdapter.validateDSLData when the DSL map has no 'metadata' object or the metadata map lacks a 'mode' key. Custom DSL imports must declare their mode in metadata so the adapter knows how to interpret the rest of the document. The message is intentionally terse.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/dsl/adapters/CustomDSLAdapter.java:151

	}

	// TODO
	@Override
	public ChatBot mapToChatBot(Map<String, Object> data) {
		return null;
	}

	// TODO
	@Override
	public Map<String, Object> chatbotToMap(ChatBot chatBot) {
		return null;
	}

	@Override
	public void validateDSLData(Map<String, Object> data) {
		Map<String, Object> metadataMap = (Map<String, Object>) data.get("metadata");
		if (metadataMap == null || !metadataMap.containsKey("mode")) {
			throw new IllegalArgumentException("invalid dsl");
		}
	}

	@Override
	public Serializer getSerializer() {
		return serializer;
	}

	@Override
	public Boolean supportDialect(DSLDialectType dialectType) {
		return DSLDialectType.CUSTOM.equals(dialectType);
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add a metadata object containing at least a 'mode' key: {"metadata": {"mode": "..."}}
2. Set mode to the value expected by your custom app (e.g. chatbot/workflow as defined by AppMetadata constants)
3. Re-export the DSL from the Studio UI so metadata is included
4. Ensure you are using the adapter that matches your DSL format

Example fix

// before
dslData.put("nodes", nodes);

// after
dslData.put("metadata", Map.of("mode", "workflow"));
dslData.put("nodes", nodes);

Object meta = data.get("metadata");
if (!(meta instanceof Map) || !((Map<?, ?>) meta).containsKey("mode")) {
    throw new IllegalArgumentException("custom DSL requires metadata.mode");
}

boolean hasMetadataMode(Map<String,Object> data) { return data.get("metadata") instanceof Map<?,?> m && m.containsKey("mode"); }

try { customAdapter.validateDSLData(data); } catch (IllegalArgumentException e) { log.warn("Custom DSL rejected: metadata/mode missing"); throw e; }

When it happens

Trigger: Calling validateDSLData or importDSL with a map where data.get("metadata") is null; metadata exists but contains no 'mode' key; hand-built maps passed directly to the custom adapter.

Common situations: Building a custom DSL map programmatically and forgetting the metadata block; copying only the node/edge portion of an export; stripping metadata during preprocessing; using the generic adapter on a DSL that belongs to Agent/Dify/Studio adapters.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• invalid agent dsl: missing 'agent' object or flat agent fiel
• invalid agent dsl: 'type/agent_class' and 'name' are require
• invalid dify dsl
• ${type} requires valid configuration
• ${type} requires 'name' field

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