What causes "Error code must not be null." in flowable/flowable-engine?

Pass a non-null, non-empty string as the errorCode when constructing the BusinessError

flowable/flowable-engine · error · FlowableIllegalArgumentException

Error code must not be null.

Error message

Error code must not be null.

What it means

BusinessError.setErrorCode throws FlowableIllegalArgumentException("Error code must not be null.") when a BusinessError (or subclass) is constructed with a null error code. Business errors are used e.g. in business-rule task / BpmnError semantics where a non-null error code is required by contract.

Source

Thrown at modules/flowable-engine-common-api/src/main/java/org/flowable/common/engine/api/delegate/BusinessError.java:55

    protected BusinessError(String errorCode) {
        super("");
        setErrorCode(errorCode);
    }

    protected BusinessError(String errorCode, String message) {
        super(message);
        setErrorCode(errorCode);
    }

    protected BusinessError(String errorCode, String message, Throwable cause) {
        super(message, cause);
        setErrorCode(errorCode);
    }

    protected void setErrorCode(String errorCode) {
        if (errorCode == null) {
            throw new FlowableIllegalArgumentException("Error code must not be null.");
        }
        if (errorCode.isEmpty()) {
            throw new FlowableIllegalArgumentException("Error code must not be empty.");
        }
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }

    public VariableContainer getAdditionalDataContainer() {
        return additionalDataContainer;
    }

    public void setAdditionalDataContainer(VariableContainer additionalDataContainer) {
        this.additionalDataContainer = additionalDataContainer;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass a non-null, non-empty string as the errorCode when constructing the BusinessError
If the code is computed, default it (e.g. code != null ? code : "DEFAULT_ERROR") before constructing
Audit custom BusinessError subclasses to ensure constructors always call super with a valid code

Example fix

// before
String code = (String) execution.getVariable("errorCode");
throw new BusinessError(code, null);
// after
String code = Objects.toString(execution.getVariable("errorCode"), "DEFAULT_BUSINESS_ERROR");
throw new BusinessError(code, null);

Defensive patterns

Strategy: validation

Validate before calling

// guard before constructing a BusinessError
if (errorCode == null) {
    throw new IllegalArgumentException("Business error code must be provided");
}

Try / catch

try {
    throw new BusinessError(code, cause);
} catch (FlowableIllegalArgumentException e) {
    LOGGER.error("Invalid business error code: {}", e.getMessage());
    throw new BusinessError("DEFAULT_BUSINESS_ERROR", cause);
}

Prevention

Never pass raw process variables as error codes without null-checking
Default computed codes before construction
Audit custom BusinessError subclasses for constructor paths that skip the code
Keep error codes as named constants instead of dynamic values where possible

When it happens

Trigger: Invoking a BusinessError constructor with null as errorCode, or calling setErrorCode(null) via the protected setter from a subclass.

Common situations: Dynamically computing an error code from a variable or process value that is null, custom BusinessError subclasses not initializing the code, or refactoring where the code constant was removed.

Related errors

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