{"record":{"id":"822dd203b97a4c50","repo":"alibaba/spring-ai-alibaba","slug":"condition-keys-cannot-be-null-or-empty","errorCode":null,"errorMessage":"Condition keys cannot be null or empty","messagePattern":"Condition keys cannot be null or empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ConditionalGraphBuildingStrategy.java","lineNumber":149,"sourceCode":"\t/**\n\t * Validates conditional-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateConditionalConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getConditionalAgents() == null || config.getConditionalAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Conditional flow requires at least one conditional agent mapping\");\n\t\t}\n\n\t\t// Ensure root agent is a FlowAgent for input key access\n\t\tif (!(config.getRootAgent() instanceof FlowAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"Conditional flow requires root agent to be a FlowAgent\");\n\t\t}\n\n\t\t// Validate that all condition keys are non-empty\n\t\tfor (String condition : config.getConditionalAgents().keySet()) {\n\t\t\tif (condition == null || condition.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Condition keys cannot be null or empty\");\n\t\t\t}\n\t\t}\n\t}\n\n}\n","sourceCodeStart":131,"sourceCodeEnd":155,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ConditionalGraphBuildingStrategy.java#L131-L155","documentation":"Every key in the conditionalAgents map is used as a routing condition string; validateConditionalConfig rejects null, empty, or whitespace-only keys because the router could never match them, silently breaking dispatch. Thrown as IllegalArgumentException.","triggerScenarios":"Building a conditional graph with Map.of(...) cannot hold null keys, so this typically fires with HashMap usage where a key is null, or with keys like \"\" or \" \" produced by dynamic configuration (Nacos config, DB rows, YAML lists).","commonSituations":"Loading branch conditions from external config where an entry has no name; trimming failed; programmatically generated keys where a variable was empty.","solutions":["Sanitize condition keys before building: strip whitespace and reject/skip blank entries","Validate external config (YAML/Nacos/DB) at load time so blank branch names never reach the builder","Add a unit test asserting every conditionalAgents key is non-blank"],"exampleFix":"// before\nMap<String, Agent> agents = new HashMap<>();\nagents.put(blankFromConfig, agentA);\n// after\nString key = rawKey == null ? null : rawKey.trim();\nif (key != null && !key.isEmpty()) { agents.put(key, agentA); }","handlingStrategy":"validation","validationCode":"config.getConditionalAgents().keySet().forEach(k -> { if (k == null || k.trim().isEmpty()) throw new IllegalArgumentException(\"Blank condition key in conditionalAgents\"); });","typeGuard":"static boolean allKeysNonBlank(Map<String, Agent> m) { return m == null || m.keySet().stream().allMatch(k -> k != null && !k.trim().isEmpty()); }","tryCatchPattern":"try { return builder.build(); } catch (IllegalArgumentException e) { log.error(\"Conditional config invalid: {}\", e.getMessage()); throw e; }","preventionTips":["Trim and filter branch keys loaded from external config at load time","Reject blank branch names where the config is first parsed","Add unit tests for externally sourced flow definitions"],"tags":["configuration","validation","conditional-routing"],"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-17T15:17:12.973Z"}