alibaba/spring-ai-alibaba · error · IllegalArgumentException

Agent name cannot be null or empty

Error message

Agent name cannot be null or empty

What it means

AbstractAgentLoader.loadAgent validates the agent name before lookup: null, empty, or whitespace-only names are rejected with IllegalArgumentException. This is the first of two guards (the second being NoSuchElementException for unknown names). It enforces that callers address agents by a real, non-blank identifier from the loader's name-to-agent map.

Source

Thrown at spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/AbstractAgentLoader.java:132

		for (Agent agent : beans.values()) {
			String name = agent.name();
			if (result.putIfAbsent(name, agent) != null) {
				log.warn("Duplicate agent name '{}', keeping first. Consider using unique agent names for Studio.", name);
			}
		}
		return result;
	}

	@Override
	@Nonnull
	public List<String> listAgents() {
		return List.copyOf(getAgentMap().keySet());
	}

	@Override
	public Agent loadAgent(String name) {
		if (name == null || name.trim().isEmpty()) {
			throw new IllegalArgumentException("Agent name cannot be null or empty");
		}
		Agent agent = getAgentMap().get(name);
		if (agent == null) {
			throw new NoSuchElementException("Agent not found: " + name);
		}
		return agent;
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure the caller passes a valid agent name listed by loader.listAgents(); log available names when validation fails.
2. Validate the name (null/blank check) at the entry point (controller/config) and return a 400 before reaching the loader.
3. If the name comes from configuration, add a non-empty default or fail-fast at startup when the property is missing/blank.
4. Fix route/client code so the agent-name path variable or request parameter is actually supplied.

Example fix

// before
String name = request.getParameter("agent");
Agent agent = agentLoader.loadAgent(name); // IllegalArgumentException when param absent

// after
String name = request.getParameter("agent");
if (name == null || name.isBlank()) {
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
        "'agent' parameter is required; available: " + agentLoader.listAgents());
}
Agent agent = agentLoader.loadAgent(name);

if (name == null || name.isBlank()) {
    throw new IllegalArgumentException("agent name required; available: " + agentLoader.listAgents());
}

static boolean isValidAgentName(String name) { return name != null && !name.isBlank(); }

try {
    Agent a = agentLoader.loadAgent(name);
} catch (IllegalArgumentException e) {
    // blank/null name -> return HTTP 400 to the client
} catch (NoSuchElementException e) {
    // unknown name -> return HTTP 404 with available agent names
}

When it happens

Trigger: Calling loadAgent(null), loadAgent(""), or loadAgent(" ") directly; a REST/controller layer forwarding a missing or blank path variable (e.g., GET /agents// or an unbound {name}) into loadAgent; config-driven agent resolution where the configured agent name property is empty.

Common situations: A route parameter not being populated (path variable typo in mapping), an empty agent-name entry in application.yml/properties, UI/API clients sending requests without the agent name, code reading an env/config value that defaults to empty string before calling the loader.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• item cannot be null
• Either language or code must be provided.
• Code must not be null
• oss object name is invalid
• ${type} requires valid configuration

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