conductor-oss/conductor · error · IllegalArgumentException

Agent start requires agentName or inline agent construction

Error message

Agent start requires agentName or inline agent construction details

What it means

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.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java:836

    }

    private void validateStartSource(AgentStartRequest request) {
        boolean hasName = StringUtils.isNotEmpty(request.getName());
        boolean hasInlineConfig =
                request.getAgentConfig() != null
                        || StringUtils.isNotEmpty(request.getFramework())
                        || request.getRawConfig() != null
                        || request.getSkillRef() != null;

        if (request.getVersion() != null && !hasName) {
            throw new IllegalArgumentException("agentVersion requires agentName");
        }
        if (hasName && hasInlineConfig) {
            throw new IllegalArgumentException(
                    "Specify either agentName/agentVersion or inline agent construction details, not both");
        }
        if (!hasName && !hasInlineConfig) {
            throw new IllegalArgumentException(
                    "Agent start requires agentName or inline agent construction details");
        }
    }

    private boolean hasMedia(List<String> media) {
        if (media == null || media.isEmpty()) {
            return false;
        }
        return media.stream().anyMatch(item -> item != null && !item.isBlank());
    }

    private boolean isNotEmpty(Map<String, Object> map) {
        return map != null && !map.isEmpty();
    }

    @SuppressWarnings("unchecked")
    public Map<String, Object> getAgentDef(String name, Integer version) {
        WorkflowDef def;

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Provide agentName (for a deployed agent) or one of agentConfig/framework+rawConfig/skillRef (for inline).
2. If using a deployed agent, set the name field.
3. If compiling inline, set agentConfig or framework with rawConfig.

Example fix

// before
AgentStartRequest req = AgentStartRequest.builder()
    .prompt("hello")
    // no agent source -> error
    .build();
service.start(req);

// after
AgentStartRequest req = AgentStartRequest.builder()
    .name("my_agent")
    .prompt("hello")
    .build();
service.start(req);

boolean hasName = StringUtils.isNotEmpty(request.getName());
boolean hasInline = request.getAgentConfig() != null
    || StringUtils.isNotEmpty(request.getFramework())
    || request.getRawConfig() != null
    || request.getSkillRef() != null;
if (!hasName && !hasInline) {
    return ResponseEntity.badRequest()
        .body("Specify agentName or inline agent config");
}
service.start(request);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Start request is required
• Agent execution requires a non-empty prompt, at least one me
• agentVersion requires agentName
• Specify either agentName/agentVersion or inline agent constr
• inspectPlan: agentConfig is required

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/b380361cb2330f74. Report an issue: GitHub.