flowable/flowable-engine · error · FlowableIllegalArgumentException

instanceId is null

Error message

instanceId is null

What it means

HistoricDecisionExecutionQueryImpl.instanceId(String) throws FlowableIllegalArgumentException when the instanceId argument is null. The instance id scopes historic decision executions to a process/case instance; because a null would create an invalid filter, the builder validates and throws immediately.

Source

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

            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");
        }
        this.executionId = executionId;
        return this;
    }
    
    @Override
    public DmnHistoricDecisionExecutionQuery activityId(String activityId) {
        if (activityId == null) {
            throw new FlowableIllegalArgumentException("activityId is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call instanceId(...) when the code actually runs within a process/case instance with a valid id
2. Branch on context: for standalone evaluations query by decisionKey/deploymentId instead of instanceId
3. Null-check the instance id source before chaining the filter

Example fix

// before
query.instanceId(execution.getProcessInstanceId()); // null for standalone decisions
// after
String pid = execution != null ? execution.getProcessInstanceId() : null;
if (pid != null) {
    query.instanceId(pid);
} else {
    query.decisionKey(decisionKey);
}

if (instanceId == null) { throw new IllegalArgumentException("instanceId required when filtering decision history by instance"); }

boolean hasInstanceId(DelegateExecution ex) { return ex != null && ex.getProcessInstanceId() != null; }

try { query.instanceId(pid); } catch (FlowableIllegalArgumentException e) { log.info("Standalone decision evaluation; skipping instanceId filter"); }

When it happens

Trigger: Calling dmnHistoryService.createHistoricDecisionExecutionQuery().instanceId(null), commonly when the process instance id is taken from an execution context that is absent (e.g. decision invoked standalone, outside a process instance).

Common situations: Standalone DMN evaluations that have no instance id but code unconditionally filters by it; asynchronous jobs whose execution context no longer resolves; handlers that copy instanceId from a request body that omitted it.

Related errors

• decisionDefinitionId is null
• deploymentId is null
• decisionKey is null
• executionId is null
• activityId is null

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