{"record":{"id":"fd62556cd14abb29","repo":"alibaba/spring-ai-alibaba","slug":"agent-not-found","errorCode":null,"errorMessage":"Agent not found: ","messagePattern":"Agent not found: ","errorType":"exception","errorClass":"NoSuchElementException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/AbstractAgentLoader.java","lineNumber":136,"sourceCode":"\t\t\t}\n\t\t}\n\t\treturn result;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic List<String> listAgents() {\n\t\treturn List.copyOf(getAgentMap().keySet());\n\t}\n\n\t@Override\n\tpublic Agent loadAgent(String name) {\n\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Agent name cannot be null or empty\");\n\t\t}\n\t\tAgent agent = getAgentMap().get(name);\n\t\tif (agent == null) {\n\t\t\tthrow new NoSuchElementException(\"Agent not found: \" + name);\n\t\t}\n\t\treturn agent;\n\t}\n}\n","sourceCodeStart":118,"sourceCodeEnd":141,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/AbstractAgentLoader.java#L118-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nAgent agent = loader.loadAgent(\"chatbot \");\n// after\nString name = requestedName == null ? null : requestedName.trim();\nif (!loader.getAgentMap().containsKey(name)) {\n    throw new IllegalArgumentException(\"Unknown agent '\" + name + \"'; available: \" + loader.getAgentMap().keySet());\n}\nAgent agent = loader.loadAgent(name);","handlingStrategy":"validation","validationCode":"if (name == null || name.isBlank() || !loader.getAgentMap().containsKey(name.trim())) {\n    throw new IllegalArgumentException(\"Unknown agent '\" + name + \"'; available: \" + loader.getAgentMap().keySet());\n}","typeGuard":null,"tryCatchPattern":"try {\n    Agent agent = loader.loadAgent(name);\n} catch (NoSuchElementException e) {\n    logger.warn(\"Agent not registered: {} — available: {}\", name, loader.getAgentMap().keySet());\n    return fallbackAgentOr404(name);\n}","preventionTips":["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"],"tags":["java","nosuch-element","agent-registry","lookup-failed"],"backgroundTag":"resource-not-found","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}