apache/shardingsphere · error · MCPExecutionModeRequiredException

%s execution_mode is required.

Error message

%s execution_mode is required.

What it means

Thrown by WorkflowExecutionService.requireExecutionMode when the apply tool is invoked with an empty execution_mode string. The workflow apply operation is ambiguous without an explicit mode (e.g. preview vs. apply), so the service rejects the request with MCPExecutionModeRequiredException and includes suggested arguments for a preview run.

Source

Thrown at mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowExecutionService.java:107

        }
        Map<String, Object> invalidArtifactResponse = validateApplyArtifacts(workflowSessionContext, snapshot, actualExecutionMode, workflowApplyArtifactValidator);
        if (!invalidArtifactResponse.isEmpty()) {
            return invalidArtifactResponse;
        }
        WorkflowApplyOutcome applyOutcome = new WorkflowApplyOutcome();
        if (WorkflowLifecycle.EXECUTION_MODE_PREVIEW.equalsIgnoreCase(actualExecutionMode)) {
            return previewApply(workflowSessionContext, snapshot);
        }
        if (isManualOnly(actualExecutionMode)) {
            return applyManualOnly(workflowSessionContext, snapshot, applyOutcome);
        }
        return applyAutomatically(workflowSessionContext, queryFacade, executionFacade, workflowRuntimeHandler, sessionId, snapshot,
                actualExecutionMode, applyOutcome);
    }
    
    private String requireExecutionMode(final WorkflowContextSnapshot snapshot, final String executionMode) {
        if (executionMode.isEmpty()) {
            throw new MCPExecutionModeRequiredException(WorkflowToolDescriptors.APPLY_TOOL_NAME, EXECUTION_MODES, createPreviewSuggestedArguments(snapshot));
        }
        String result = executionMode.toLowerCase(Locale.ENGLISH);
        if (!EXECUTION_MODES.contains(result)) {
            throw new MCPInvalidExecutionModeException(WorkflowToolDescriptors.APPLY_TOOL_NAME, EXECUTION_MODES, createPreviewSuggestedArguments(snapshot));
        }
        return result;
    }
    
    private void requireApprovedSteps(final WorkflowContextSnapshot snapshot, final List<String> approvedSteps) {
        if (null == approvedSteps || approvedSteps.isEmpty()) {
            return;
        }
        for (String each : approvedSteps) {
            if (!ALLOWED_APPROVAL_STEPS.contains(each)) {
                throw new MCPInvalidApprovedStepsException(ALLOWED_APPROVAL_STEPS, createPreviewSuggestedArguments(snapshot));
            }
        }
    }

View on GitHub (pinned to e952770a21)

Solutions

  1. Supply execution_mode with an allowed value (e.g. "preview" before any real apply) — the accepted set is returned in the exception and matches WorkflowLifecycle.EXECUTION_MODES.
  2. Use the suggestedArguments payload from MCPExecutionModeRequiredException to retry with a valid preview request.
  3. If your client omits optional fields, make sure execution_mode is not being serialized as "" instead of being absent.

Example fix

// before
arguments.put("execution_mode", "");
// after
arguments.put("execution_mode", "preview");
Defensive patterns

Strategy: validation

Validate before calling

if (null == executionMode || executionMode.trim().isEmpty()) {
    executionMode = "preview"; // or refuse to call apply until the user picks a mode
}

Type guard

const hasExecutionMode = m => typeof m?.execution_mode === "string" && m.execution_mode.trim().length > 0;

Try / catch

try {
    applyResult = applyTool.call(request);
} catch (final MCPExecutionModeRequiredException ex) {
    // ex carries EXECUTION_MODES and preview suggestedArguments; retry with them
}

Prevention

When it happens

Trigger: Invoking the workflow apply tool with execution_mode set to "" (present but empty) or an empty-valued field. A missing/null field that resolves to an empty string in the request mapping also triggers it.

Common situations: An LLM agent builds the apply request from a template and fills execution_mode with an empty string; a client forwards a form field that was never populated; confusion between the plan tool (which needs no mode) and the apply tool (which requires one).

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/c20af2e13d434cce. Report an issue: GitHub.