{"record":{"id":"3e72967baf952b74","repo":"alibaba/spring-ai-alibaba","slug":"agent-name-cannot-be-null-or-empty","errorCode":null,"errorMessage":"Agent name cannot be null or empty","messagePattern":"Agent name cannot be null or empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-studio/src/main/java/com/alibaba/cloud/ai/agent/studio/loader/AbstractAgentLoader.java","lineNumber":132,"sourceCode":"\t\tfor (Agent agent : beans.values()) {\n\t\t\tString name = agent.name();\n\t\t\tif (result.putIfAbsent(name, agent) != null) {\n\t\t\t\tlog.warn(\"Duplicate agent name '{}', keeping first. Consider using unique agent names for Studio.\", name);\n\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":114,"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#L114-L141","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the caller passes a valid agent name listed by loader.listAgents(); log available names when validation fails.","Validate the name (null/blank check) at the entry point (controller/config) and return a 400 before reaching the loader.","If the name comes from configuration, add a non-empty default or fail-fast at startup when the property is missing/blank.","Fix route/client code so the agent-name path variable or request parameter is actually supplied."],"exampleFix":"// before\nString name = request.getParameter(\"agent\");\nAgent agent = agentLoader.loadAgent(name); // IllegalArgumentException when param absent\n\n// after\nString name = request.getParameter(\"agent\");\nif (name == null || name.isBlank()) {\n    throw new ResponseStatusException(HttpStatus.BAD_REQUEST,\n        \"'agent' parameter is required; available: \" + agentLoader.listAgents());\n}\nAgent agent = agentLoader.loadAgent(name);","handlingStrategy":"validation","validationCode":"if (name == null || name.isBlank()) {\n    throw new IllegalArgumentException(\"agent name required; available: \" + agentLoader.listAgents());\n}","typeGuard":"static boolean isValidAgentName(String name) { return name != null && !name.isBlank(); }","tryCatchPattern":"try {\n    Agent a = agentLoader.loadAgent(name);\n} catch (IllegalArgumentException e) {\n    // blank/null name -> return HTTP 400 to the client\n} catch (NoSuchElementException e) {\n    // unknown name -> return HTTP 404 with available agent names\n}","preventionTips":["Validate agent-name path variables/parameters at the controller with a 400 response.","Fail fast at startup if a configured agent name is missing or blank.","Discover valid names via listAgents() and surface them in error messages."],"tags":["argument-validation","null-check","agent-loader","http-400"],"backgroundTag":"missing-required-argument","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}