apache/shardingsphere · error · MCPExecutionModeRequiredException

%s execution_mode is required.

Error message

%s execution_mode is required.

What it means

Thrown by WorkflowExecutionToolHandler.handle as MCPExecutionModeRequiredException when the workflow apply tool is called without an execution_mode argument (missing or empty string). Execution of workflow artifacts is safety-critical, so the tool refuses to guess; the exception advertises the accepted modes (preview, review_then_execute, manual_only) and a suggested preview argument set.

Source

Thrown at mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/tool/handler/workflow/WorkflowExecutionToolHandler.java:65

    
    private final WorkflowRuntimeDefinitionRegistry workflowRuntimeDefinitionRegistry;
    
    @Override
    public Class<MCPFeatureRequestContext> getContextType() {
        return MCPFeatureRequestContext.class;
    }
    
    @Override
    public String getToolName() {
        return WorkflowToolDescriptors.APPLY_TOOL_NAME;
    }
    
    @Override
    public MCPSuccessPayload handle(final MCPFeatureRequestContext requestContext, final Map<String, Object> arguments) {
        MCPToolArguments toolArguments = new MCPToolArguments(arguments);
        String executionMode = toolArguments.getStringArgument(WorkflowFieldNames.EXECUTION_MODE);
        if (executionMode.isEmpty()) {
            throw new MCPExecutionModeRequiredException(WorkflowToolDescriptors.APPLY_TOOL_NAME, List.of(WorkflowLifecycle.EXECUTION_MODE_PREVIEW,
                    WorkflowLifecycle.EXECUTION_MODE_REVIEW_THEN_EXECUTE, WorkflowLifecycle.EXECUTION_MODE_MANUAL_ONLY),
                    createPreviewSuggestedArguments(arguments));
        }
        WorkflowSessionContext workflowSessionContext = requestContext.getWorkflowSessionContext();
        WorkflowContextSnapshot snapshot = workflowSessionContext.getRequired(toolArguments.getStringArgument(WorkflowFieldNames.PLAN_ID));
        WorkflowRuntimeDefinition workflowRuntimeDefinition = workflowRuntimeDefinitionRegistry.getRequired(snapshot);
        return new MCPMapPayload(executionService.apply(workflowSessionContext, requestContext.getQueryFacade(), requestContext.getExecutionFacade(),
                workflowRuntimeDefinition.getRuntimeHandler(), workflowRuntimeDefinition.getApplyArtifactValidator(),
                requestContext.getSessionIdentity().getSessionId(),
                snapshot, toolArguments.getStringCollectionArgument(WorkflowFieldNames.APPROVED_STEPS), executionMode));
    }
    
    private static Map<String, Object> createPreviewSuggestedArguments(final Map<String, Object> arguments) {
        Map<String, Object> result = new LinkedHashMap<>(arguments);
        result.remove(WorkflowFieldNames.EXECUTION_MODE);
        result.put(WorkflowFieldNames.EXECUTION_MODE, WorkflowLifecycle.EXECUTION_MODE_PREVIEW);
        return result;
    }

View on GitHub (pinned to e952770a21)

Solutions

  1. Add execution_mode to the apply call with one of the advertised values — start with preview for safety
  2. Read the allowed values from the exception payload (it includes EXECUTION_MODE_PREVIEW/REVIEW_THEN_EXECUTE/MANUAL_ONLY and suggested arguments) instead of hard-coding assumptions
  3. Make the field mandatory in your client schema/validation so the request never leaves without it

Example fix

// before
apply({"plan_id": "p1"})

// after
apply({"plan_id": "p1", "execution_mode": "preview"})
Defensive patterns

Strategy: try-catch

Validate before calling

if (!arguments.containsKey("execution_mode") || String.valueOf(arguments.get("execution_mode")).isBlank()) {
    arguments.put("execution_mode", "preview"); // safe default
}

Try / catch

try {
    return applyTool.handle(ctx, arguments);
} catch (MCPExecutionModeRequiredException e) {
    // e carries allowed modes and a suggested preview argument set
    arguments.put("execution_mode", e.getSuggestedArguments().containsKey("execution_mode")
            ? e.getSuggestedArguments().get("execution_mode") : "preview");
    return applyTool.handle(ctx, arguments);
}

Prevention

When it happens

Trigger: toolArguments.getStringArgument(WorkflowFieldNames.EXECUTION_MODE) returns "" because the arguments map has no execution_mode key or an empty value. Any apply call like apply({"plan_id": "p1"}) without execution_mode triggers it.

Common situations: Agent clients omitting execution_mode and assuming a default; version upgrades that introduced the required field into an existing integration; UI forms that send the field only when non-empty.

Related errors

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