conductor-oss/conductor · error · IllegalArgumentException

agentConfig is required when framework is not specified

Error message

agentConfig is required when framework is not specified

What it means

Thrown by AgentService.resolveConfig when framework is not specified (null or empty) and agentConfig is also null. Without a framework, resolveConfig uses the native agentConfig field directly — if that is absent, there is no config to compile. IllegalArgumentException maps to HTTP 400. Note: validateStartSource checks for the presence of an inline source, but resolveConfig is reached later (e.g. via compile() or startInline) and provides this additional guard.

Source

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

     * Resolve the AgentConfig from a AgentStartRequest. If {@code framework} is set, normalize the
     * raw config via the appropriate normalizer. Otherwise, use the native {@code agentConfig}
     * field directly.
     */
    private AgentConfig resolveConfig(AgentStartRequest request) {
        if (request.getFramework() != null && !request.getFramework().isEmpty()) {
            log.debug("Normalizing framework '{}' agent config", request.getFramework());
            if ("skill".equals(request.getFramework())
                    && request.getRawConfig() == null
                    && request.getSkillRef() != null) {
                if (skillRegistryService == null) {
                    throw new IllegalStateException("Skill registry is not available");
                }
                request.setRawConfig(skillRegistryService.resolveRawConfig(request.getSkillRef()));
            }
            return normalizerRegistry.normalize(request.getFramework(), request.getRawConfig());
        }
        if (request.getAgentConfig() == null) {
            throw new IllegalArgumentException(
                    "agentConfig is required when framework is not specified");
        }
        return request.getAgentConfig();
    }

    // ── SSE Streaming ──────────────────────────────────────────────

    /** Open an SSE stream for an agent execution. Replays missed events on reconnect. */
    public SseEmitter openStream(String executionId, Long lastEventId) {
        log.info("Opening SSE stream for execution {} (lastEventId={})", executionId, lastEventId);
        workflowService.getExecutionStatus(executionId, false);
        return streamRegistry.register(executionId, lastEventId);
    }

    /** Respond to a pending HITL task in an agent execution. */
    public void respond(String executionId, Map<String, Object> output) {
        log.info("Responding to execution {}: {}", executionId, output);

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Set either framework (with rawConfig or skillRef) or a non-null agentConfig on the request.
2. If using a framework normalizer path, ensure framework is non-empty.
3. Validate that agentConfig is populated before calling compile() or start().

Example fix

// before
AgentStartRequest req = AgentStartRequest.builder()
    .prompt("hello")
    // no framework, no agentConfig -> error
    .build();
service.compile(req);

// after
AgentStartRequest req = AgentStartRequest.builder()
    .agentConfig(AgentConfig.builder().name("a").build())
    .prompt("hello")
    .build();
service.compile(req);

if (StringUtils.isEmpty(request.getFramework())
    && request.getAgentConfig() == null) {
    return ResponseEntity.badRequest()
        .body("Provide agentConfig or set a framework");
}
service.compile(request);

When it happens

Trigger: Calling compile() with a request that has no framework and no agentConfig; calling start() in inline mode where the inline config was not actually populated; the rawConfig/skillRef path was not taken because framework was unset.

Common situations: SDK builds the request intending to use framework+rawConfig but forgets to set framework; agentConfig was conditionally nulled by upstream logic; the request was constructed for the name-based path but name was empty so it fell through to inline.

Related errors

• inspectPlan: agentConfig is required
• inspectPlan: plan is required
• inspectPlan: agentConfig.strategy must be 'plan_execute', go
• pruneExecutions: olderThanDays must be >= 1, got ${olderThan
• Start request is required

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