flowable/flowable-engine · error · IllegalArgumentException

The field 'script' should be set on the TaskListener

Error message

The field 'script' should be set on the TaskListener

What it means

ScriptTaskListener requires a 'script' field expression to know what script to execute when the task listener fires. If the 'script' field was not configured on the listener in the BPMN XML, notify() throws this IllegalArgumentException immediately when the listener is invoked.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/bpmn/listener/ScriptTaskListener.java:41

 * @author Rich Kroll
 * @author Joram Barrez
 */
public class ScriptTaskListener implements TaskListener {

    private static final long serialVersionUID = -8915149072830499057L;

    protected Expression script;

    protected Expression language;

    protected Expression resultVariable;

    protected boolean autoStoreVariables;

    @Override
    public void notify(DelegateTask delegateTask) {
        if (script == null) {
            throw new IllegalArgumentException("The field 'script' should be set on the TaskListener");
        }

        if (language == null) {
            throw new IllegalArgumentException("The field 'language' should be set on the TaskListener");
        }

        ScriptingEngines scriptingEngines = Context.getProcessEngineConfiguration().getScriptingEngines();

        Object result = scriptingEngines.evaluate(script.getExpressionText(), language.getExpressionText(), delegateTask, autoStoreVariables);

        if (resultVariable != null) {
            delegateTask.setVariable(resultVariable.getExpressionText(), result);
        }
    }

    public void setScript(Expression script) {
        this.script = script;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Add a <activiti:field name='script'><activiti:string>...script text...</activiti:string></activiti:field> to the task listener declaration in the BPMN XML
2. If building the listener in code, call setScript with a FixedValue or Expression before deployment
3. Validate the process definition at deploy time to catch missing listener fields before runtime

Example fix

// before (BPMN)
<activiti:taskListener event="create" class="org.activiti.engine.impl.bpmn.listener.ScriptTaskListener" />
// after
<activiti:taskListener event="create" class="org.activiti.engine.impl.bpmn.listener.ScriptTaskListener">
  <activiti:field name="script">
    <activiti:string>println(task.name)</activiti:string>
  </activiti:field>
  <activiti:field name="language">
    <activiti:string>javascript</activiti:string>
  </activiti:field>
</activiti:taskListener>

// XML check before deployment
if (!xml.contains("name=\"script\"")) {
  throw new IllegalStateException("ScriptTaskListener is missing the 'script' field");
}

try {
  repositoryService.createDeployment().addClasspathResource(processXml).deploy();
} catch (IllegalArgumentException e) {
  // listener fields incomplete — fix BPMN config and redeploy
}

When it happens

Trigger: A script task listener is declared in BPMN XML (or via listener configuration) without an <activiti:field name='script'> element, and the listener fires on a task event (create/assignment/complete/delete).

Common situations: Hand-edited BPMN XML missing the script field extension element; programmatically built listeners where setScript was never called; copy-pasted listener configs where the script field was accidentally removed.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• The field 'language' should be set on the TaskListener
• The field 'script' should be set on the TaskListener
• The field 'language' should be set on the TaskListener
• decisionTableReferenceKey is a required field extension for
• Could not resolve key for: ${eventDefinitionKey} for ${execu

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