alibaba/spring-ai-alibaba · error · IllegalArgumentException

invalid agent dsl: data is null

Error message

invalid agent dsl: data is null

What it means

validateDSLData in AgentDSLAdapter rejects a null dslData map at the very start of importDSL — the uploaded/parsed DSL JSON had no data payload, so no agent can be constructed. A fail-fast guard before field validation.

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:125

					if (childRoot.get("input_keys") instanceof List<?> ciks) {
						child.setInputKeys((List<String>) (List<?>) ciks);
					}
					child.setOutputKey(asString(childRoot.get("output_key")));
					if (childRoot.get("handle") instanceof Map<?, ?> ch) {
						child.setHandle((Map<String, Object>) ch);
					}
					subs.add(child);
				}
			}
			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;
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure the request body contains a valid agent DSL document
2. Check that the DSL deserializer is actually invoked and returns a non-null map
3. Validate the payload is non-empty before calling importDSL

Example fix

// before
gateway.parse(body); // returns null for empty body
agentAdapter.importDSL(parsed);
// after
if (parsed != null) { agentAdapter.importDSL(parsed); }

if (dslData == null || dslData.isEmpty()) { throw new IllegalArgumentException("agent dsl payload required"); }

boolean isValidAgentDsl(Map<String,Object> dsl) { return dsl != null && !dsl.isEmpty() && (dsl.containsKey("agent") || !dsl.isEmpty()); }

try { agentAdapter.importDSL(dsl); } catch (IllegalArgumentException e) { /* return 400 invalid dsl */ }

When it happens

Trigger: Calling AgentDSLAdapter.importDSL(null) or passing a parse result that came out null (e.g. empty request body deserialized to null).

Common situations: Empty request bodies on the import endpoint, serializers returning null for blank input, upstream code dropping the parsed map.

Related errors

• TOOL_PARAMS_MISSING
• MISSING_PARAMS
• Dataset ID cannot be null
• ttlUnit cannot be null
• key cannot be null

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