flowable/flowable-engine · error · FlowableIllegalStateException

A script is required

Error message

A script is required

What it means

ScriptEngineRequest.Builder.build() refuses to construct a request when the script field is null or empty, throwing FlowableIllegalStateException('A script is required'). It is the builder-construction-time guard for the newer ScriptEngineRequest API.

Solutions

1. Add .script("<non-empty code>") to the builder chain before build().
2. Verify the resource/config supplying the script text is loaded and non-blank.
3. Throw a clearer domain error at load time when the script source is blank.

Example fix

// before
ScriptEngineRequest req = ScriptEngineRequest.builder().language("javascript").build();

// after
ScriptEngineRequest req = ScriptEngineRequest.builder()
    .language("javascript")
    .script("return input + 1;")
    .build();

if (script == null || script.isEmpty()) {
    throw new IllegalStateException("ScriptEngineRequest requires a non-empty script before build()");
}

boolean hasScript(String s) { return s != null && !s.isEmpty(); }

try {
    ScriptEngineRequest req = builder.build();
} catch (FlowableIllegalStateException e) {
    throw new ConfigurationException("Script request builder missing script text", e);
}

When it happens

Trigger: Calling ScriptEngineRequest.builder()...build() without script(...), or with script("") — typically when the script content is loaded from a resource/variable that is empty.

Common situations: Externalized script file missing on classpath so an empty string was loaded; conditional code paths that skip setting the script; refactoring that renamed the script constant.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• language is required
• script is required
• A resource name is mandatory
• An event definition key is mandatory
• language is empty

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

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/scripting/ScriptEngineRequest.java:140

            this.additionalResolvers.add(additionalResolver);
            return this;
        }

        /**
         * Configure an {@link ScriptTraceEnhancer}
         * which is called, when a ScriptTrace is created.
         * Allows to provide additional context information for a script trace by allow to "tag"
         * the script invocation with additional meta information.
         * Script traces are produced in case of errors and/or when a {@link ScriptTraceListener} is configured.
         */
        public Builder traceEnhancer(ScriptTraceEnhancer enhancer) {
            this.traceEnhancer = enhancer;
            return this;
        }

        public ScriptEngineRequest build() {
            if (script == null || script.isEmpty()) {
                throw new FlowableIllegalStateException("A script is required");
            }
            return new ScriptEngineRequest(script,
                    language,
                    scopeContainer,
                    inputVariableContainer != null ? inputVariableContainer : scopeContainer,
                    storeScriptVariables,
                    additionalResolvers,
                    traceEnhancer);
        }
    }

    private ScriptEngineRequest(String script,
            String language,
            VariableContainer scopeContainer,
            VariableContainer inputVariableContainer,
            boolean storeScriptVariables,
            List<Resolver> additionalResolvers,
            ScriptTraceEnhancer errorTraceEnhancer) {

View on GitHub (pinned to d6d39ce1c6)