apache/shardingsphere · error · MCPInvalidExecutionModeException

%s execution_mode must be one of %s.

Error message

%s execution_mode must be one of %s.

What it means

Thrown by WorkflowExecutionService.requireExecutionMode when execution_mode is non-empty but, after lowercasing, is not one of the supported WorkflowLifecycle.EXECUTION_MODES values. The request is rejected with MCPInvalidExecutionModeException, which carries the tool name, the full allowed-mode list, and preview-suggested arguments.

Source

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

        }
        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));
            }
        }
    }
    
    private Map<String, Object> checkApplyPreconditions(final String sessionId, final WorkflowContextSnapshot snapshot, final String executionMode,
                                                        final List<String> approvedSteps) {
        if (!WorkflowLifecycleUtils.isOwnedBySession(sessionId, snapshot)) {

View on GitHub (pinned to e952770a21)

Solutions

1. Read the allowed modes from the MCPInvalidExecutionModeException payload (or WorkflowLifecycle.EXECUTION_MODES) and retry with one of them exactly, e.g. "preview".
2. Start with "preview" mode when unsure — the exception's suggestedArguments already encode a valid preview request.
3. Pin the client and server to compatible versions so the mode vocabulary matches.

Example fix

// before
arguments.put("execution_mode", "dry-run");
// after
arguments.put("execution_mode", "preview");

Set<String> allowed = WorkflowLifecycle.EXECUTION_MODES;
String candidate = executionMode == null ? "" : executionMode.toLowerCase(Locale.ENGLISH);
if (!allowed.contains(candidate)) { throw new IllegalArgumentException("use one of " + allowed); }

const isExecutionMode = m => EXECUTION_MODES.includes((m?.execution_mode ?? "").toLowerCase());

try {
    applyTool.call(request);
} catch (final MCPInvalidExecutionModeException ex) {
    // message lists valid modes; retry with one of them ("preview" is always a safe start)
}

When it happens

Trigger: Calling the workflow apply tool with an execution_mode such as "execute", "dry-run", "auto", or a misspelling of an allowed value; matching is case-insensitive but exact-string after lowercasing, so plurals or synonyms fail.

Common situations: Agents guessing mode names ("dry_run" instead of "preview"), documentation drift between client SDK and server versions where the mode vocabulary changed, or copy-paste from a different tool's API.

Related errors

• %s execution_mode is required.
• %s execution_mode is required.
• %s execution_mode must be one of %s.
• %s execution_mode is required.
• approved_steps must contain only %s.

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