conductor-oss/conductor · error · IllegalArgumentException

Agent execution requires a non-empty prompt, at least one me

Error message

Agent execution requires a non-empty prompt, at least one media item, or non-empty context.

What it means

Thrown by AgentService.validateStartInput when the AgentStartRequest has no prompt, no media items, and no context map. The start flow requires at least one of these to give the agent something to work on. hasMedia checks for non-blank items; isNotEmpty checks for a non-empty map. IllegalArgumentException maps to HTTP 400.

Source

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

        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;

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

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Provide at least one of: a non-blank prompt, at least one non-blank media URL/reference, or a non-empty context map.
2. Validate at the caller/SDK layer that prompt is non-empty before sending.
3. If the agent is meant to resume from context, ensure the context map is populated.

Example fix

// before
AgentStartRequest req = AgentStartRequest.builder()
    .name("my_agent")
    .prompt("")  // empty
    .build();
service.start(req); // -> error

// after
AgentStartRequest req = AgentStartRequest.builder()
    .name("my_agent")
    .prompt("Summarize the latest tickets")
    .build();
service.start(req);

boolean hasInput = StringUtils.isNotBlank(request.getPrompt())
    || (request.getMedia() != null && !request.getMedia().isEmpty())
    || (request.getContext() != null && !request.getContext().isEmpty());
if (!hasInput) {
    return ResponseEntity.badRequest()
        .body("Provide a prompt, media, or context");
}
service.start(request);

When it happens

Trigger: Starting an agent with an empty prompt string, null media, and null/empty context; all three input fields are blank/empty; the request deserialized with defaults that left all inputs absent.

Common situations: UI submit with an empty text box and no attachment; SDK builds the request but forgets to set the prompt; automated trigger sends a heartbeat-style request with no actual task.

Related errors

• Start request is required
• 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/1c34743c576081f2. Report an issue: GitHub.