jd-opensource/joyagent-jdgenie · error · IllegalArgumentException

step_index is required for mark_step command

Error message

step_index is required for mark_step command

What it means

markStep validates its arguments before delegating to plan.updateStepStatus. When the params map lacks `step_index`, it throws IllegalArgumentException because a step cannot be identified without its index.

Solutions

1. Include `step_index` (integer, 0-based) in every mark_step call.
2. Validate tool-call arguments against the declared JSON schema before dispatching.
3. Improve the message to name the missing key and expected type for faster debugging.

Example fix

// before
Integer stepIndex = (Integer) params.get("step_index");
// after
Object raw = params.get("step_index");
if (!(raw instanceof Integer stepIndex)) {
    throw new IllegalArgumentException("step_index (integer) is required for mark_step command");
}

if (!params.containsKey("step_index") || !(params.get("step_index") instanceof Integer)) {
    throw new IllegalArgumentException("mark_step requires integer step_index");
}

static boolean hasStepIndex(Map<String, Object> params) {
    return params.get("step_index") instanceof Integer;
}

try {
    tool.execute(params);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("step_index is required")) {
        // fix args and retry with a valid step_index
    } else throw e;
}

When it happens

Trigger: Calling PlanningTool with command=mark_step and a params map that omits `step_index` (only step_status/step_notes provided), or the LLM emitting malformed tool arguments.

Common situations: LLM generates incomplete tool-call JSON; caller builds the params map programmatically and forgets the index; schema drift between prompt documentation and tool implementation.

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

• 集合名称为空！
• collectionName is null!
• Command is required
• title, and steps are required for create command
• No plan exists. Create a plan first.

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

Appendix: source

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

        if (plan == null) {
            throw new IllegalStateException("No plan exists. Create a plan first.");
        }

        plan.update(title, steps);
        return "我已更新plan";
    }

    private String markStep(Map<String, Object> params) {
        Integer stepIndex = (Integer) params.get("step_index");
        String stepStatus = (String) params.get("step_status");
        String stepNotes = (String) params.get("step_notes");

        if (plan == null) {
            throw new IllegalStateException("No plan exists. Create a plan first.");
        }

        if (stepIndex == null) {
            throw new IllegalArgumentException("step_index is required for mark_step command");
        }

        plan.updateStepStatus(stepIndex, stepStatus, stepNotes);

        return String.format("我已标记plan %d 为 %s", stepIndex, stepStatus);
    }

    private String finishPlan(Map<String, Object> params) {
        if (Objects.isNull(plan)) {
            plan = new Plan();
        } else {
            for (int stepIndex = 0; stepIndex < plan.getSteps().size(); stepIndex++) {
                plan.updateStepStatus(stepIndex, "completed", "");
            }
        }
        return "我已更新plan为完成状态";
    }

View on GitHub (pinned to 2417e0b8b6)