{"record":{"id":"dc5335b2b7cacebe","repo":"alibaba/spring-ai-alibaba","slug":"agent-name-must-not-be-empty","errorCode":null,"errorMessage":"Agent name must not be empty","messagePattern":"Agent name must not be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java","lineNumber":59,"sourceCode":"import java.lang.reflect.Field;\nimport java.lang.reflect.Method;\nimport java.util.ArrayList;\nimport java.util.Collections;\nimport java.util.List;\n\npublic class DefaultBuilder extends Builder {\n\n\tprivate static final Logger logger = LoggerFactory.getLogger(DefaultBuilder.class);\n\n\tpublic static final String POSSIBLE_LLM_TOOL_NAME_CHANGE_WARNING\n\t\t\t\t= \"LLM may have adapted the tool name '{}', especially if the name was truncated due to length limits. If this is the case, you can customize the prefixing and processing logic using McpToolNamePrefixGenerator\";\n\n\t@Override\n\tpublic ReactAgent build() {\n\n\t\t// Validate name is not empty\n\t\tif (!StringUtils.hasText(this.name)) {\n\t\t\tthrow new IllegalArgumentException(\"Agent name must not be empty\");\n\t\t}\n\n\t\t// Validate either chatClient or model is provided\n\t\tif (chatClient == null && model == null) {\n\t\t\tthrow new IllegalArgumentException(\"Either chatClient or model must be provided\");\n\t\t}\n\n\t\t// Get source options from ChatClient (when provided) or from ChatModel (when building from model).\n\t\tChatOptions sourceOptions = (chatClient != null)\n\t\t\t\t? getChatClientDefaultOptions(chatClient)\n\t\t\t\t: getChatModelDefaultOptions(model);\n\t\tChatOptions effectiveOptions = mergeSourceOptionsWithAgentOptions(sourceOptions, this.chatOptions);\n\n\t\tif (chatClient == null) {\n\t\t\tChatClient.Builder clientBuilder = ChatClient.builder(model,\n\t\t\t\t\tthis.observationRegistry == null ? ObservationRegistry.NOOP : this.observationRegistry,\n\t\t\t\t\tthis.customObservationConvention, this.advisorObservationConvention);\n\t\t\tif (effectiveOptions != null) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java#L41-L77","documentation":"DefaultBuilder.build() validates that the agent name is non-empty (StringUtils.hasText) and throws IllegalArgumentException before constructing the ReactAgent. Every agent requires a name used for graph node naming and hooks.","triggerScenarios":"Calling ReactAgent.builder().build() without ever calling .name(...), or with name(null)/name(\"\")/name(\"   \").","commonSituations":"Copy-pasting a builder chain and dropping the name() line; loading agent name from config that is missing or blank.","solutions":["Call .name(\"my-agent\") with a non-blank string on the builder before build().","Validate the configured name early (fail fast at startup) before reaching build().","If the name comes from config, provide a default or check hasText beforehand."],"exampleFix":"// before\nReactAgent agent = ReactAgent.builder().model(model).build();\n// after\nReactAgent agent = ReactAgent.builder().name(\"research-agent\").model(model).build();","handlingStrategy":"validation","validationCode":"if (agentName == null || agentName.isBlank()) throw new IllegalArgumentException(\"Agent name must be a non-blank string before build()\");","typeGuard":null,"tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { throw new IllegalStateException(\"Agent misconfigured: \" + e.getMessage(), e); }","preventionTips":["Always call .name(...) immediately after ReactAgent.builder().","Centralize agent construction in a factory that asserts required fields.","Fail fast at startup with a config validation pass."],"tags":["builder-validation","empty-string","illegal-argument"],"backgroundTag":"empty-required-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}