flowable/flowable-engine · error · FlowableIllegalArgumentException

Invalid variable scope: '" + scope + "'

Error message

Invalid variable scope: '" + scope + "'

What it means

RestVariable.getScopeFromString maps a scope string (global/local, case-insensitive) to a RestVariableScope enum. A string that matches no enum constant name triggers FlowableIllegalArgumentException; this runs whenever setScope is called with a non-null value on REST variable payloads.

Solutions

1. Send only "global" or "local" for the scope field (case-insensitive).
2. Omit the scope field if the default is acceptable (it maps to null).
3. Trim/clean the scope string before calling setScope.
4. Replace legacy Activiti scope vocabulary (execution/task) with Flowable's global/local.

Example fix

// before
restVariable.setScope("execution");
// after
restVariable.setScope("local");

if (scope != null && !scope.trim().equalsIgnoreCase("global") && !scope.trim().equalsIgnoreCase("local")) {
    throw new IllegalArgumentException("Scope must be global or local");
}

boolean isValidScope(String s) { return s == null || "global".equalsIgnoreCase(s) || "local".equalsIgnoreCase(s); }

try { restVariable.setScope(scope); } catch (FlowableIllegalArgumentException e) { /* normalize to global/local */ }

When it happens

Trigger: Deserializing/setting the "scope" field of a RestVariable with a value other than GLOBAL or LOCAL (e.g. "execution", "task", "process"), from variable GET/PUT request payloads or query parameters.

Common situations: Clients using Activiti-style scope names ("execution"/"task") that Flowable's REST API does not accept, untrimmed whitespace, or custom code calling setScope with engine-level strings.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Execution ' ' does not have a variable ' ' in scope
• Unsupported variable query operation: " + friendlyName
• Variable '" + restVariable.getName() + "' has unsupported…
• A group or a user is required to create an identity link.
• A group or a user is required to create an identity link.

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/1ef345883583791f. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/engine/variable/RestVariable.java:65

        String scope = null;
        if (variableScope != null) {
            scope = variableScope.name().toLowerCase();
        }
        return scope;
    }

    public void setScope(String scope) {
        setVariableScope(getScopeFromString(scope));
    }

    public static RestVariableScope getScopeFromString(String scope) {
        if (scope != null) {
            for (RestVariableScope s : RestVariableScope.values()) {
                if (s.name().equalsIgnoreCase(scope)) {
                    return s;
                }
            }
            throw new FlowableIllegalArgumentException("Invalid variable scope: '" + scope + "'");
        } else {
            return null;
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)