{"record":{"id":"b380361cb2330f74","repo":"conductor-oss/conductor","slug":"agent-start-requires-agentname-or-inline-agent-con","errorCode":null,"errorMessage":"Agent start requires agentName or inline agent construction details","messagePattern":"Agent start requires agentName or inline agent construction details","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":836,"sourceCode":"    }\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\n    private boolean isNotEmpty(Map<String, Object> map) {\n        return map != null && !map.isEmpty();\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public Map<String, Object> getAgentDef(String name, Integer version) {\n        WorkflowDef def;","sourceCodeStart":818,"sourceCodeEnd":854,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L818-L854","documentation":"Thrown by AgentService.validateStartSource when the request has neither an agentName nor any inline agent construction details (agentConfig, framework, rawConfig, skillRef). The start API requires the agent to be specified somehow — this error means the source of the agent definition is entirely absent. IllegalArgumentException maps to HTTP 400.","triggerScenarios":"Request only contains prompt/media/context but no agent source fields; all source fields are null/empty; the request was partially constructed and the agent source was never set.","commonSituations":"Caller assumes the server will pick a default agent; SDK builder leaves all agent-source fields unset; the agent name field was removed during a refactor but the prompt was kept.","solutions":["Provide agentName (for a deployed agent) or one of agentConfig/framework+rawConfig/skillRef (for inline).","If using a deployed agent, set the name field.","If compiling inline, set agentConfig or framework with rawConfig."],"exampleFix":"// before\nAgentStartRequest req = AgentStartRequest.builder()\n    .prompt(\"hello\")\n    // no agent source -> error\n    .build();\nservice.start(req);\n\n// after\nAgentStartRequest req = AgentStartRequest.builder()\n    .name(\"my_agent\")\n    .prompt(\"hello\")\n    .build();\nservice.start(req);","handlingStrategy":"validation","validationCode":"boolean hasName = StringUtils.isNotEmpty(request.getName());\nboolean hasInline = request.getAgentConfig() != null\n    || StringUtils.isNotEmpty(request.getFramework())\n    || request.getRawConfig() != null\n    || request.getSkillRef() != null;\nif (!hasName && !hasInline) {\n    return ResponseEntity.badRequest()\n        .body(\"Specify agentName or inline agent config\");\n}\nservice.start(request);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set either agentName or an inline config source.","Use SDK builder validation to enforce at least one source.","Test the request construction path for missing fields."],"tags":["validation","start","bad-request","missing-input"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}