alibaba/spring-ai-alibaba · error · IllegalArgumentException

invalid agent dsl: 'type/agent_class' and 'name' are require

Error message

invalid agent dsl: 'type/agent_class' and 'name' are required

What it means

Thrown by AgentDSLAdapter.validateDSLData when the agent root object was found but is missing either a non-blank type ('type' or 'agent_class') or a non-blank 'name'. Both fields are mandatory to identify which agent implementation to instantiate and how to register it. After this check, type-specific constraints are validated by validateAgentTypeSpecificConstraints.

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/AgentDSLAdapter.java:134

			}
			agent.setSubAgents(subs);
		}

		return new App(metadata, agent);
	}

	private void validateDSLData(Map<String, Object> dslData) {
		if (dslData == null) {
			throw new IllegalArgumentException("invalid agent dsl: data is null");
		}
		Map<String, Object> root = getAgentRoot(dslData);
		if (root == null) {
			throw new IllegalArgumentException("invalid agent dsl: missing 'agent' object or flat agent fields");
		}
		String type = firstNonBlank((String) root.get("type"), (String) root.get("agent_class"));
		String name = (String) root.get("name");
		if (isBlank(type) || isBlank(name)) {
			throw new IllegalArgumentException("invalid agent dsl: 'type/agent_class' and 'name' are required");
		}
		// 针对不同 Agent 类型的校验
		validateAgentTypeSpecificConstraints(type, root);
	}

	private void validateAgentTypeSpecificConstraints(String type, Map<String, Object> root) {
		if (type == null || root == null) {
			return;
		}

		// 使用 AgentTypeProvider 进行校验
		AgentTypeProvider provider = providerRegistry.get(type);
		if (provider != null) {
			provider.validateDSL(root);
		}
	}

	private AppMetadata mapToMetadata(Map<String, Object> data) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add a non-blank 'type' (or legacy 'agent_class') and 'name' to the agent object in the DSL
2. Check for whitespace-only values — isBlank() treats them as missing
3. Compare against a known-good exported DSL for the same agent type to confirm required fields
4. Confirm the agent type string matches a supported type in validateAgentTypeSpecificConstraints

Example fix

// before
{"agent": {"name": ""}}

// after
{"agent": {"type": "SimpleAgent", "name": "my-agent"}}

Map<String,Object> agent = (Map<String,Object>) dslData.get("agent");
String type = agent != null ? (String) agent.getOrDefault("type", (String) agent.get("agent_class")) : null;
String name = agent != null ? (String) agent.get("name") : null;
if (type == null || type.isBlank() || name == null || name.isBlank()) throw new IllegalArgumentException("agent type and name are required");

boolean hasRequiredAgentFields(Map<String,Object> agent) { return agent != null && Optional.ofNullable((String) agent.get("type")).or(() -> Optional.ofNullable((String) agent.get("agent_class"))).map(s -> !s.isBlank()).orElse(false) && Optional.ofNullable((String) agent.get("name")).map(s -> !s.isBlank()).orElse(false); }

try { adapter.importDSL(dslData); } catch (IllegalArgumentException e) { if (e.getMessage().contains("type/agent_class")) { log.error("Missing agent type/name in DSL"); } throw e; }

When it happens

Trigger: Importing a DSL whose agent object has a name but no type/agent_class; an agent object with type but a blank or missing name; firstNonBlank of ("type","agent_class") yields null/empty string; whitespace-only values.

Common situations: Template DSL files with placeholder fields left empty; migration scripts that drop 'agent_class' from older DSL versions; programmatic DSL construction where the builder skipped required fields; renaming an agent and accidentally clearing the name field.

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 dsl
• 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/1c54b16e13d4108a. Report an issue: GitHub.