What causes "Task formKey is null" in flowable/flowable-engine?

Null-check the form key and skip setting the filter when null

flowable/flowable-engine · error · FlowableIllegalArgumentException

Task formKey is null

Error message

Task formKey is null

What it means

taskFormKey(String) requires a non-null formKey; passing null throws FlowableIllegalArgumentException("Task formKey is null"). The library validates eagerly so the generated query always has a usable form-key filter.

Solutions

Null-check the form key and skip setting the filter when null
Provide a concrete form key value or resolve it before querying
If any form key is acceptable, use a different filter or none

Example fix

// before
query.taskFormKey(formKey); // may be null
// after
if (formKey != null) { query.taskFormKey(formKey); }

Defensive patterns

Strategy: validation

Validate before calling

if (formKey != null) { query.taskFormKey(formKey); }

Type guard

boolean hasFormKey(String formKey) { return formKey != null && !formKey.isBlank(); }

Try / catch

try {
    query.taskFormKey(formKey);
} catch (FlowableIllegalArgumentException e) {
    // query without form-key restriction
}

Prevention

Null-check optional form keys before applying the filter
Resolve form keys from the form repository before querying history
Wrap Flowable query setters in null-safe helper methods used across the codebase

When it happens

Trigger: Calling taskFormKey(null), commonly when the form key comes from an optional configuration value, a null process variable, or an unset request parameter.

Common situations: Search forms where the form-key field is optional; service code forwarding a variable that is not set in the given process definition version.

Related errors

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

Appendix: source

Thrown at modules/flowable-task-service/src/main/java/org/flowable/task/service/impl/HistoricTaskInstanceQueryImpl.java:1876

            this.withoutCategory = true;
        }
        return this;
    }

    @Override
    public HistoricTaskInstanceQuery taskWithFormKey() {
        if (inOrStatement) {
            currentOrQueryObject.withFormKey = true;
        } else {
            this.withFormKey = true;
        }
        return this;
    }

    @Override
    public HistoricTaskInstanceQuery taskFormKey(String formKey) {
        if (formKey == null) {
            throw new FlowableIllegalArgumentException("Task formKey is null");
        }

        if (inOrStatement) {
            currentOrQueryObject.formKey = formKey;
        } else {
            this.formKey = formKey;
        }
        return this;
    }

    @Override
    public HistoricTaskInstanceQuery taskCandidateUser(String candidateUser) {
        if (candidateUser == null) {
            throw new FlowableIllegalArgumentException("Candidate user is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.candidateUser = candidateUser;

View on GitHub (pinned to d6d39ce1c6)