What causes "Agent not found: " in alibaba/spring-ai-alibaba?

List registered agents first (e.g. via the loader's agent-name listing / getAgentMap().keySet()) and use an exact existing name

alibaba/spring-ai-alibaba · error · NoSuchElementException

Agent not found:

Error message

Agent not found:

What it means

AbstractAgentLoader.loadAgent(String name) throws NoSuchElementException when no agent registered under the given name exists in the agent map. The loader keeps agents in a name-keyed map (getAgentMap()); lookup by an unknown or stale name yields null and this error. It means the name does not match any currently registered agent, not that the agent failed to build.

Solutions

List registered agents first (e.g. via the loader's agent-name listing / getAgentMap().keySet()) and use an exact existing name
Check the name for typos and case-sensitivity; trim surrounding whitespace
Verify the agent's YAML/config file was actually loaded and registered by the ConfigAgentWatcher before calling loadAgent
If the agent should exist, check the studio loader startup logs for registration failures

Example fix

// before
Agent agent = loader.loadAgent("chatbot ");
// after
String name = requestedName == null ? null : requestedName.trim();
if (!loader.getAgentMap().containsKey(name)) {
    throw new IllegalArgumentException("Unknown agent '" + name + "'; available: " + loader.getAgentMap().keySet());
}
Agent agent = loader.loadAgent(name);

Defensive patterns

Strategy: validation

Validate before calling

if (name == null || name.isBlank() || !loader.getAgentMap().containsKey(name.trim())) {
    throw new IllegalArgumentException("Unknown agent '" + name + "'; available: " + loader.getAgentMap().keySet());
}

Try / catch

try {
    Agent agent = loader.loadAgent(name);
} catch (NoSuchElementException e) {
    logger.warn("Agent not registered: {} — available: {}", name, loader.getAgentMap().keySet());
    return fallbackAgentOr404(name);
}

Prevention

Fetch the agent-name list from the loader before resolving a user-supplied name
Always trim and case-normalize agent names at the API boundary
Log available agent names when a lookup fails to speed up diagnosis

When it happens

Trigger: Calling loadAgent("foo") where "foo" was never registered, where the agent was deregistered/removed, or where the name differs in case/whitespace from the registered key. Null or blank names throw IllegalArgumentException instead.

Common situations: Typo in agent name in request payload or config; Studio request referencing an agent from YAML config that failed to load; name changed after refactor; agent file removed while a client still references it.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

			}
		}
		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)