What causes "key is null" in flowable/flowable-engine?

Null-check and only apply the key criterion when present

flowable/flowable-engine · error · FlowableIllegalArgumentException

key is null

Error message

key is null

What it means

appDefinitionKey(null) throws FlowableIllegalArgumentException because the app definition key is used in an exact-match predicate and null is treated as a caller mistake rather than 'no filter'. Validation runs in the query builder before execution.

Source

Thrown at modules/flowable-app-engine/src/main/java/org/flowable/app/engine/impl/repository/AppDefinitionQueryImpl.java:151

        this.deploymentId = deploymentId;
        return this;
    }

    @Override
    public AppDefinitionQueryImpl deploymentIds(Set<String> deploymentIds) {
        if (deploymentIds == null) {
            throw new FlowableIllegalArgumentException("ids are null");
        } else if (deploymentIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("ids is an empty collection");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

Null-check and only apply the key criterion when present
Fail earlier with a clearer message if the key is required by your business logic
Catch FlowableIllegalArgumentException and map it to a 400 response

Example fix

// before
query.appDefinitionKey(appKey);
// after
if (appKey != null) {
    query.appDefinitionKey(appKey);
}

Defensive patterns

Strategy: validation

Validate before calling

if (key != null) {
    query.appDefinitionKey(key);
}

Type guard

boolean isApplicable(String v) { return v != null && !v.isEmpty(); }

Try / catch

try {
    query.appDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage(), e);
}

Prevention

Validate configuration-provided keys at startup so they are never null at query time
Null-check keys pulled from other entities before use
Use Optional<String> for optional key filters and apply conditionally

When it happens

Trigger: Calling appDefinitionQuery.appDefinitionKey(key) with a null key — typically an unbound variable, a missing config/property value, or the result of a lookup that found nothing.

Common situations: Application configuration missing the app key; passing another entity's null key attribute; optional REST parameter forwarded unconditionally.

Related errors

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