{"record":{"id":"006f6c8468283bb5","repo":"conductor-oss/conductor","slug":"specify-either-agentname-agentversion-or-inline-ag","errorCode":null,"errorMessage":"Specify either agentName/agentVersion or inline agent construction details, not both","messagePattern":"Specify either agentName/agentVersion or inline agent construction details, not both","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java","lineNumber":832,"sourceCode":"            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\n    private boolean isNotEmpty(Map<String, Object> map) {\n        return map != null && !map.isEmpty();\n    }","sourceCodeStart":814,"sourceCodeEnd":850,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java#L814-L850","documentation":"Thrown by AgentService.validateStartSource when the request contains both an agentName and inline agent construction details (agentConfig, framework, rawConfig, or skillRef). The start API supports two mutually exclusive modes: reference a deployed agent by name, or provide an inline config. Mixing both is ambiguous. IllegalArgumentException maps to HTTP 400.","triggerScenarios":"Request sets agentName alongside agentConfig; agentName is provided together with framework+rawConfig; agentName plus skillRef in the same request.","commonSituations":"SDK defaults agentConfig in the builder and the caller also sets name, not realizing they conflict; UI form submits both the selected agent name and the edited inline config; migration code populates all fields defensively.","solutions":["Choose one mode: either agentName (optionally with agentVersion) for a deployed agent, OR inline config (agentConfig/framework/rawConfig/skillRef) for ad-hoc compilation.","Clear the inline config fields when using name-based start.","Clear the name field when using inline config start."],"exampleFix":"// before\nAgentStartRequest req = AgentStartRequest.builder()\n    .name(\"my_agent\")\n    .agentConfig(myConfig)  // both set -> error\n    .prompt(\"hello\")\n    .build();\n\n// after (mode 1: deployed agent)\nAgentStartRequest req = AgentStartRequest.builder()\n    .name(\"my_agent\")\n    .prompt(\"hello\")\n    .build();\n// after (mode 2: inline)\nAgentStartRequest req = AgentStartRequest.builder()\n    .agentConfig(myConfig)\n    .prompt(\"hello\")\n    .build();","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 config, not both\");\n}\nservice.start(request);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use mutually exclusive request construction in the SDK (builder branches).","Clear inline fields when selecting a deployed agent by name.","Validate the request mode before calling start()."],"tags":["validation","start","bad-request","conflicting-input"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}