conductor-oss/conductor · error · IllegalArgumentException

inspectPlan: agentConfig is required

Error message

inspectPlan: agentConfig is required

What it means

Thrown by AgentService.inspectPlan when the InspectPlanRequest is null or its agentConfig field is null. inspectPlan is a compile-only validation path that runs the PAC (Plan-And-Compile) task against a plan without dispatching. It requires both an AgentConfig (tool list, model, harness timeout) and a plan. IllegalArgumentException maps to HTTP 400.

Source

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

                .build();
    }

    /**
     * /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

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Ensure the InspectPlanRequest includes a fully populated AgentConfig before calling inspectPlan.
2. Add a null-check on request.getAgentConfig() in the caller before the API call.
3. If the config should come from a deployed agent, load it first via getAgentDef/getRegisteredAgent and construct the AgentConfig.

Example fix

// before
InspectPlanRequest req = new InspectPlanRequest();
req.setPlan(plan);
service.inspectPlan(req); // agentConfig is null -> error

// after
InspectPlanRequest req = new InspectPlanRequest();
req.setAgentConfig(agentConfig);
req.setPlan(plan);
service.inspectPlan(req);

if (request == null || request.getAgentConfig() == null) {
    throw new IllegalStateException(
        "Cannot inspect plan: agentConfig must be provided in the request");
}
service.inspectPlan(request);

// Java does not have structural type guards; use explicit null checks
boolean canInspect = request != null
    && request.getAgentConfig() != null
    && request.getPlan() != null;

When it happens

Trigger: Calling inspectPlan(null); calling inspectPlan with a request object whose getAgentConfig() returns null; JSON deserialization produced a partial InspectPlanRequest missing the agentConfig key.

Common situations: Offline plan-validation tool or CI step sends an incomplete request body; SDK builds the request conditionally and skips the config when the agent is pre-deployed; API client omits agentConfig thinking the server will resolve it from a stored agent name (it will not — inspectPlan does not do name-based lookup).

Related errors

• inspectPlan: plan is required
• inspectPlan: agentConfig.strategy must be 'plan_execute', go
• agentConfig is required when framework is not specified
• pruneExecutions: olderThanDays must be >= 1, got ${olderThan
• Start request is required

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