conductor-oss/conductor · error · IllegalArgumentException

agentVersion requires agentName

Error message

agentVersion requires agentName

What it means

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.

Source

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

        if (StringUtils.isNotBlank(request.getPrompt())
                || hasMedia(request.getMedia())
                || isNotEmpty(request.getContext())) {
            return;
        }
        throw new IllegalArgumentException(
                "Agent execution requires a non-empty prompt, at least one media item, or non-empty context.");
    }

    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());
    }

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Either provide both agentName and agentVersion, or omit agentVersion entirely to use the latest version of the named agent.
2. If starting inline, remove the agentVersion field from the request.
3. Add a caller-side check: if version is set, ensure name is also set.

Example fix

// before
AgentStartRequest req = AgentStartRequest.builder()
    .version(2)         // version without name
    .prompt("hello")
    .build();
service.start(req); // -> error

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

if (request.getVersion() != null && StringUtils.isEmpty(request.getName())) {
    return ResponseEntity.badRequest()
        .body("agentVersion requires agentName");
}
service.start(request);

When it happens

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

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

Related errors

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

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