flowable/flowable-engine · error · FlowableIllegalArgumentException

key is null

Error message

key is null

What it means

ChannelDefinitionQueryImpl.channelDefinitionKey() throws FlowableIllegalArgumentException when the key argument is null. The query API requires an exact key string to filter channel definitions; null is rejected at build time so the error surfaces immediately at the call site instead of as an empty or malformed database query.

Solutions

1. Pass the actual channel definition key string
2. Guard the call site: only call channelDefinitionKey(key) when key != null
3. If a partial match is intended, use channelDefinitionKeyLike(keyPattern) with a non-null pattern
4. Verify the source of the key (config file, model JSON) actually contains the key property

Example fix

// before
String key = channelModel.getKey(); // may be null
query.channelDefinitionKey(key);
// after
if (channelModel.getKey() != null) {
    query.channelDefinitionKey(channelModel.getKey());
} else {
    throw new IllegalStateException("Channel key is required");
}

if (key == null || key.isBlank()) {
    throw new IllegalArgumentException("channelDefinitionKey is required");
}
query.channelDefinitionKey(key);

boolean hasKey(String key) {
    return key != null && !key.isBlank();
}

try {
    query.channelDefinitionKey(key);
} catch (FlowableIllegalArgumentException e) {
    throw new ConfigurationException("Channel key not configured: " + e.getMessage(), e);
}

When it happens

Trigger: Calling channelDefinitionQuery().channelDefinitionKey(null), usually because the key variable originates from a model, event registry model, or config value that is unset/null.

Common situations: Looking up a channel definition whose key was never configured; typos leading to a null lookup result passed onward; deserialization of a channel model that omitted the key field.

Related errors

• Error retrieving app engine info
• ids are null
• implementation is null
• keyLike is null
• keyLikeIgnoreCase is null

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

Appendix: source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/ChannelDefinitionQueryImpl.java:173

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

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

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

    @Override
    public ChannelDefinitionQueryImpl channelDefinitionKeyLike(String keyLike) {
        if (keyLike == null) {
            throw new FlowableIllegalArgumentException("keyLike is null");
        }
        this.keyLike = keyLike;
        return this;
    }
    
    @Override
    public ChannelDefinitionQuery channelDefinitionKeyLikeIgnoreCase(String keyLikeIgnoreCase) {
        if (keyLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("keyLikeIgnoreCase is null");

View on GitHub (pinned to d6d39ce1c6)