jd-opensource/joyagent-jdgenie · error · IllegalArgumentException

Command is required

Error message

Command is required

What it means

Validation guard at the top of PlanningTool.execute: the input map is cast from JSON and the 'command' parameter selects which planning operation (create_plan, mark_step, etc.) to run. Because 'command' is the mandatory discriminator, executing without it is unrecoverable, so execute throws IllegalArgumentException before dispatching. Fires when a caller/LLM omits the command field from the planning tool arguments.

Solutions

1. Always include a non-empty command key in the tool arguments
2. Validate required keys before calling execute
3. Check the LLM tool schema/JSON emitted for the planning tool

Example fix

// before
planningTool.execute(Map.of("title", "t", "steps", List.of("s")));
// after
planningTool.execute(Map.of("command", "create", "title", "t", "steps", List.of("s")));

Object cmd = params.get("command");
if (cmd == null || cmd.toString().isEmpty()) { throw new IllegalArgumentException("command required"); }

try {
    return planningTool.execute(params);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Command is required")) { /* fix args */ }
    throw e;
}

When it happens

Trigger: Calling execute with a Map that lacks the command key, has command: null, or command: "".

Common situations: LLM emitted tool arguments without the command field, key casing mismatch (e.g. "Command"), or arguments built programmatically and command omitted.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• title, and steps are required for create command
• Input must be a Map
• Unknown command: " + command
• A plan already exists. Delete the current plan first.
• step_index is required for mark_step command

AI-assisted analysis of jd-opensource/joyagent-jdgenie@2417e0b8b6 (2026-09-08). Data as JSON: /api/errors/922def5171b62584. Report an issue: GitHub.

Appendix: source

Thrown at genie-backend/src/main/java/com/jd/genie/agent/tool/common/PlanningTool.java:129

    private Map<String, Object> getStepNotesProperty() {
        Map<String, Object> stepNotes = new HashMap<>();
        stepNotes.put("type", "string");
        stepNotes.put("description", "Additional notes for a step. Optional for mark_step command.");
        return stepNotes;
    }

    @Override
    public Object execute(Object input) {
        if (!(input instanceof Map)) {
            throw new IllegalArgumentException("Input must be a Map");
        }

        Map<String, Object> params = (Map<String, Object>) input;
        String command = (String) params.get("command");

        if (command == null || command.isEmpty()) {
            throw new IllegalArgumentException("Command is required");
        }

        Function<Map<String, Object>, String> handler = commandHandlers.get(command);
        if (handler != null) {
            return handler.apply(params);
        } else {
            throw new IllegalArgumentException("Unknown command: " + command);
        }
    }

    private String createPlan(Map<String, Object> params) {
        String title = (String) params.get("title");
        List<String> steps = (List<String>) params.get("steps");

        if (title == null || steps == null) {
            throw new IllegalArgumentException("title, and steps are required for create command");
        }

View on GitHub (pinned to 2417e0b8b6)