flowable/flowable-engine · error · ActivitiIllegalArgumentException

Error Code must not be null.

Error message

Error Code must not be null.

What it means

BpmnError requires an errorCode string used to match BPMN error boundary events. The protected setErrorCode() method rejects a null errorCode with ActivitiIllegalArgumentException. Any BpmnError constructor that receives null propagates this error, so an error event can never be thrown or matched without a code.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/delegate/BpmnError.java:49

public class BpmnError extends ActivitiException {

    private static final long serialVersionUID = 1L;

    private String errorCode;

    public BpmnError(String errorCode) {
        super("");
        setErrorCode(errorCode);
    }

    public BpmnError(String errorCode, String message) {
        super(message + " (errorCode='" + errorCode + "')");
        setErrorCode(errorCode);
    }

    protected void setErrorCode(String errorCode) {
        if (errorCode == null) {
            throw new ActivitiIllegalArgumentException("Error Code must not be null.");
        }
        if (errorCode.length() < 1) {
            throw new ActivitiIllegalArgumentException("Error Code must not be empty.");
        }
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }

    @Override
    public String toString() {
        return super.toString() + " (errorCode='" + errorCode + "')";
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the error code passed to new BpmnError(code) is a non-null string literal or resolved variable.
2. Add a null check / default before throwing: throw new BpmnError(code != null ? code : "DEFAULT_ERROR").
3. Trace where the code originates (process variable, service response) and fix the null source.

Example fix

// before
String code = (String) execution.getVariable("errCode");
throw new BpmnError(code); // NPE-ish: ActivitiIllegalArgumentException
// after
String code = (String) execution.getVariable("errCode");
if (code == null) { code = "ORDER_ERROR"; }
throw new BpmnError(code);

if (errorCode == null) throw new IllegalArgumentException("errorCode required before throwing BpmnError");

boolean isValidErrorCode(String s) { return s != null; }

try { throwOrPropagate(); } catch (ActivitiIllegalArgumentException e) { logger.error("BpmnError built with null errorCode", e); throw new BpmnError("DEFAULT_ERROR"); }

When it happens

Trigger: new BpmnError(null) or new BpmnError(message, null) — any constructor path that calls setErrorCode with a null value, e.g. passing a null variable holding the business error code.

Common situations: Java delegates or task listeners throwing BpmnError with an error code fetched from process variables or external data that turned out to be null; refactors where a constant became a nullable lookup.

Related errors

• Error Code must not be empty.
• Error retrieving app engine info
• No deployment id available
• No resource name available
• No deployment id provided

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