flowable/flowable-engine · error · FlowableIllegalArgumentException

key is null

Error message

key is null

What it means

Flowable throws FlowableIllegalArgumentException with message "key is null" when processDefinitionKey(null) is called. The key identifies the process definition (e.g. 'orderProcess'), so it is a mandatory non-null filter. Internal Flowable code paths such as alreadyExistingProcessDefinitions and findNewLatestProcessDefinitionAfterRemovalOf also rely on this method and expect a real key.

Solutions

1. Pass the actual definition key string, e.g. processDefinitionKey("orderProcess").
2. Check the variable for null before the call and fail with a domain-specific message.
3. If the key comes from a BPMN file, validate the <process id=...> attribute is present and non-empty before deploying/querying.

Example fix

// before
String key = message.getHeader("processKey"); // may be null
runtimeService.startProcessInstanceByKey(key);
// (and earlier) query.processDefinitionKey(key);
// after
String key = message.getHeader("processKey");
if (key == null) {
    throw new IllegalArgumentException("processKey header is required");
}
runtimeService.startProcessInstanceByKey(key);
query.processDefinitionKey(key);

Objects.requireNonNull(key, "process definition key is required");
query.processDefinitionKey(key);

boolean isValidKey(String key) { return key != null && key.matches("[a-zA-Z_][a-zA-Z0-9_]*"); }

try {
    query.processDefinitionKey(key);
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    throw new BadRequestException("A non-null process definition key is required");
}

When it happens

Trigger: Calling query.processDefinitionKey(key) with null key; passing a null key extracted from a ProcessDefinition entity; BPMN deployment tooling calling it without a parsed key.

Common situations: Starting processes by key where the key comes from an unresolved config property or message header; tests asserting on definitions where the process id in the BPMN XML was renamed so the stored key lookup yields null; version-upgrade scripts.

Related errors

• callbackId is null
• Candidate group is null
• Candidate group list is null
• Candidate user is null
• category is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java:184

            throw new FlowableIllegalArgumentException("ids are null");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl parentDeploymentId(String parentDeploymentId) {
        if (parentDeploymentId == null) {
            throw new FlowableIllegalArgumentException("parentDeploymentId is null");
        }
        this.parentDeploymentId = parentDeploymentId;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKey(String key) {
        if (key == null) {
            throw new FlowableIllegalArgumentException("key is null");
        }
        this.key = key;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKeyLike(String keyLike) {
        if (keyLike == null) {
            throw new FlowableIllegalArgumentException("keyLike is null");
        }
        this.keyLike = keyLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionResourceName(String resourceName) {
        if (resourceName == null) {
            throw new FlowableIllegalArgumentException("resourceName is null");

View on GitHub (pinned to d6d39ce1c6)