conductor-oss/conductor · error · IllegalArgumentException

Specify either agentName/agentVersion or inline agent constr

Error message

Specify either agentName/agentVersion or inline agent construction details, not both

What it means

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.

Source

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

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

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

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Choose one mode: either agentName (optionally with agentVersion) for a deployed agent, OR inline config (agentConfig/framework/rawConfig/skillRef) for ad-hoc compilation.
2. Clear the inline config fields when using name-based start.
3. Clear the name field when using inline config start.

Example fix

// before
AgentStartRequest req = AgentStartRequest.builder()
    .name("my_agent")
    .agentConfig(myConfig)  // both set -> error
    .prompt("hello")
    .build();

// after (mode 1: deployed agent)
AgentStartRequest req = AgentStartRequest.builder()
    .name("my_agent")
    .prompt("hello")
    .build();
// after (mode 2: inline)
AgentStartRequest req = AgentStartRequest.builder()
    .agentConfig(myConfig)
    .prompt("hello")
    .build();

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 config, not both");
}
service.start(request);

When it happens

Trigger: Request sets agentName alongside agentConfig; agentName is provided together with framework+rawConfig; agentName plus skillRef in the same request.

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

Related errors

• Start request is required
• Agent execution requires a non-empty prompt, at least one me
• agentVersion requires agentName
• 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/006f6c8468283bb5. Report an issue: GitHub.