flowable/flowable-engine · error · FlowableIllegalArgumentException

decisionKey is null

Error message

decisionKey is null

What it means

HistoricDecisionExecutionQueryImpl.decisionKey(String) throws FlowableIllegalArgumentException when the decisionKey argument is null. The key criterion is directly translated into a database filter, so Flowable requires a non-null string and throws FlowableIllegalArgumentException in the builder method.

Source

Thrown at modules/flowable-dmn-engine/src/main/java/org/flowable/dmn/engine/impl/HistoricDecisionExecutionQueryImpl.java:99

            throw new FlowableIllegalArgumentException("decisionDefinitionId is null");
        }
        this.decisionDefinitionId = decisionDefinitionId;
        return this;
    }
    
    @Override
    public DmnHistoricDecisionExecutionQuery deploymentId(String deploymentId) {
        if (deploymentId == null) {
            throw new FlowableIllegalArgumentException("deploymentId is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }
    
    @Override
    public DmnHistoricDecisionExecutionQuery decisionKey(String decisionKey) {
        if (decisionKey == null) {
            throw new FlowableIllegalArgumentException("decisionKey is null");
        }
        this.decisionKey = decisionKey;
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the actual decision key from the deployed DMN model
2. Chain decisionKey(...) only when the key is non-null; otherwise omit the filter
3. Validate the source (config/variable) returns the expected key before building the query

Example fix

// before
query.decisionKey(processVars.get("decisionKey")); // variable may be unset
// after
String key = (String) processVars.get("decisionKey");
if (key != null) {
    query.decisionKey(key);
}

if (decisionKey == null || decisionKey.isEmpty()) { throw new IllegalArgumentException("decisionKey must be non-null"); }

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

try { query.decisionKey(key); } catch (FlowableIllegalArgumentException e) { log.warn("decisionKey filter skipped: {}", e.getMessage()); }

When it happens

Trigger: Calling dmnHistoryService.createHistoricDecisionExecutionQuery().decisionKey(null), usually when the key is read from a decision reference, config property, or process variable that is unset.

Common situations: Analytics on decision executions per decision key where the key mapping is stale after a model rename; dynamically driven reports with an optional key filter; tests that query before the decision was ever evaluated with the expected key.

Related errors

• decisionDefinitionId is null
• deploymentId is null
• instanceId is null
• executionId is null
• activityId is null

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