{"record":{"id":"f2e7e9cead2491f6","repo":"conductor-oss/conductor","slug":"agentversion-requires-agentname","errorCode":null,"errorMessage":"agentVersion requires agentName","messagePattern":"agentVersion requires agentName","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":829,"sourceCode":"        if (StringUtils.isNotBlank(request.getPrompt())\n                || hasMedia(request.getMedia())\n                || isNotEmpty(request.getContext())) {\n            return;\n        }\n        throw new IllegalArgumentException(\n                \"Agent execution requires a non-empty prompt, at least one media item, or non-empty context.\");\n    }\n\n    private void validateStartSource(AgentStartRequest request) {\n        boolean hasName = StringUtils.isNotEmpty(request.getName());\n        boolean hasInlineConfig =\n                request.getAgentConfig() != null\n                        || StringUtils.isNotEmpty(request.getFramework())\n                        || request.getRawConfig() != null\n                        || request.getSkillRef() != null;\n\n        if (request.getVersion() != null && !hasName) {\n            throw new IllegalArgumentException(\"agentVersion requires agentName\");\n        }\n        if (hasName && hasInlineConfig) {\n            throw new IllegalArgumentException(\n                    \"Specify either agentName/agentVersion or inline agent construction details, not both\");\n        }\n        if (!hasName && !hasInlineConfig) {\n            throw new IllegalArgumentException(\n                    \"Agent start requires agentName or inline agent construction details\");\n        }\n    }\n\n    private boolean hasMedia(List<String> media) {\n        if (media == null || media.isEmpty()) {\n            return false;\n        }\n        return media.stream().anyMatch(item -> item != null && !item.isBlank());\n    }\n","sourceCodeStart":811,"sourceCodeEnd":847,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L811-L847","documentation":"Thrown by AgentService.validateStartSource when request.getVersion() is non-null but request.getName() is empty/null. The start API treats agentName+agentVersion as a pair to resolve a deployed agent — supplying a version without a name is ambiguous and cannot resolve. IllegalArgumentException maps to HTTP 400.","triggerScenarios":"Setting agentVersion in the request without setting agentName; JSON body has 'agentVersion' but omits or blanks 'agentName'; SDK builder sets version from a config but name is conditionally skipped.","commonSituations":"Copy-paste error in API request construction; SDK where version is set from a template but name comes from user input that was left blank; intent was to start inline but version was erroneously included.","solutions":["Either provide both agentName and agentVersion, or omit agentVersion entirely to use the latest version of the named agent.","If starting inline, remove the agentVersion field from the request.","Add a caller-side check: if version is set, ensure name is also set."],"exampleFix":"// before\nAgentStartRequest req = AgentStartRequest.builder()\n    .version(2)         // version without name\n    .prompt(\"hello\")\n    .build();\nservice.start(req); // -> error\n\n// after\nAgentStartRequest req = AgentStartRequest.builder()\n    .name(\"my_agent\")\n    .version(2)\n    .prompt(\"hello\")\n    .build();\nservice.start(req);","handlingStrategy":"validation","validationCode":"if (request.getVersion() != null && StringUtils.isEmpty(request.getName())) {\n    return ResponseEntity.badRequest()\n        .body(\"agentVersion requires agentName\");\n}\nservice.start(request);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair agentVersion with agentName.","Omit agentVersion to use the latest version of the named agent.","Add a caller-side assertion that version implies name."],"tags":["validation","start","bad-request","agent-name"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}