conductor-oss/conductor · error · IllegalArgumentException

Start request is required

Error message

Start request is required

What it means

Thrown by AgentService.validateStartInput (called from start) when the AgentStartRequest is null. This is the first validation gate in the start flow — a null request means no body was deserialized or null was passed programmatically. IllegalArgumentException maps to HTTP 400.

Source

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

        if (normalizedConfig != null) {
            metadata.put("normalizedAgentDef", MAPPER.convertValue(normalizedConfig, Map.class));
        }
    }

    private static int toInt(Object value) {
        if (value instanceof Number) return ((Number) value).intValue();
        if (value instanceof String) {
            try {
                return Integer.parseInt((String) value);
            } catch (NumberFormatException ignored) {
            }
        }
        return 0;
    }

    private void validateStartInput(AgentStartRequest request) {
        if (request == null) {
            throw new IllegalArgumentException("Start request is required");
        }
        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;

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Ensure the request body is a valid JSON AgentStartRequest object.
2. Add a null check in the controller layer before delegating to AgentService.
3. Validate the API client is sending Content-Type: application/json with a non-empty body.

Example fix

// before
// POST /api/agent/start with empty body
service.start(null); // -> error

// after
// Controller-level guard
if (request == null) {
    return ResponseEntity.badRequest().body("Request body is required");
}
service.start(request);

if (request == null) {
    return ResponseEntity.badRequest().body("Request body is required");
}
service.start(request);

When it happens

Trigger: POST /api/agent/start with an empty or missing request body; calling service.start(null) programmatically; a proxy/gateway stripped the body before forwarding.

Common situations: API client sends Content-Type without a body; SDK marshalling bug produces null; controller receives a malformed JSON that deserializes to null.

Related errors

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