conductor-oss/conductor · error · IllegalArgumentException

inspectPlan: plan is required

Error message

inspectPlan: plan is required

What it means

Thrown by AgentService.inspectPlan when the InspectPlanRequest.plan field is null. The plan is the workflow plan (typically from the planner LLM or a hand-rolled static plan for offline validation) that the PAC task compiles into a WorkflowDef. Without it there is nothing to inspect. IllegalArgumentException maps to HTTP 400.

Source

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

    /**
     * /dg #6: compile a plan against a PLAN_EXECUTE harness config and return the resulting
     * Conductor WorkflowDef — without dispatching it. Lets callers inspect what PAC would produce
     * before running.
     *
     * <p>Uses the same {@link PlanAndCompileTask#inspectPlan(Map, String, String, int, Set, Map)}
     * path the runtime SUB_WORKFLOW dispatch uses, so there's exactly one compiler — no
     * inspect-only divergence.
     *
     * <p>Caller must supply both the agent config (so the compile knows about the tool list, model,
     * harness timeout) and the plan (typically what the planner LLM emitted, but can be a
     * hand-rolled static plan for offline validation).
     */
    public PlanAndCompileTask.InspectResult inspectPlan(InspectPlanRequest request) {
        if (request == null || request.getAgentConfig() == null) {
            throw new IllegalArgumentException("inspectPlan: agentConfig is required");
        }
        if (request.getPlan() == null) {
            throw new IllegalArgumentException("inspectPlan: plan is required");
        }
        AgentConfig config = request.getAgentConfig();
        if (config.getName() == null || config.getName().isEmpty()) {
            config.setName("agent_inspect");
        }
        if (config.getStrategy() != AgentConfig.Strategy.PLAN_EXECUTE) {
            throw new IllegalArgumentException(
                    "inspectPlan: agentConfig.strategy must be 'plan_execute', got '"
                            + (config.getStrategy() == null
                                    ? "null"
                                    : config.getStrategy().toValue())
                            + "'");
        }

        // Replicate what MultiAgentCompiler.compilePlanExecute computes
        // before calling PAC at runtime — so the inspect compile sees the
        // same inputs the real one would.
        String workflowName = MultiAgentCompiler.planWorkflowName(config.getName());

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Ensure the planner output is non-null before constructing the InspectPlanRequest.
2. Validate request.getPlan() != null in the caller before calling inspectPlan.
3. If the plan comes from an LLM, add a null/empty guard on the planner response and fail earlier with a clearer message.

Example fix

// before
InspectPlanRequest req = new InspectPlanRequest();
req.setAgentConfig(config);
req.setPlan(plannerResult); // plannerResult is null -> error

// after
if (plannerResult == null) {
    throw new IllegalStateException("Planner returned no plan");
}
req.setPlan(plannerResult);
service.inspectPlan(req);

if (request.getPlan() == null) {
    throw new IllegalStateException("Planner produced no plan; cannot inspect");
}
service.inspectPlan(request);

When it happens

Trigger: Calling inspectPlan with agentConfig set but plan omitted; the planner LLM returned null or an empty response and it was passed through unchecked; the plan key was misspelled in the JSON request body.

Common situations: CI validation pipeline calls inspectPlan with only the config because the plan-generation step failed silently; integration with a planner service that returns null on error without the caller checking; JSON field name mismatch (e.g. 'workflow_plan' instead of 'plan').

Related errors

• inspectPlan: agentConfig is required
• inspectPlan: agentConfig.strategy must be 'plan_execute', go
• pruneExecutions: olderThanDays must be >= 1, got ${olderThan
• Start request is required
• Agent execution requires a non-empty prompt, at least one me

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