flowable/flowable-engine · error · FlowableIllegalArgumentException

caseInstanceId is required

Error message

caseInstanceId is required

What it means

GetHistoricEntityLinkChildrenForCaseInstanceCmd is a command that fetches the historic entity links that are children of a given case instance. The Flowable engine validates command arguments eagerly: its constructor throws FlowableIllegalArgumentException when the caseInstanceId is null, because the command cannot be executed meaningfully without an id. This fail-fast check happens before the command is ever queued in the command executor.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/GetHistoricEntityLinkChildrenForCaseInstanceCmd.java:38

import org.flowable.common.engine.api.FlowableIllegalArgumentException;
import org.flowable.common.engine.api.scope.ScopeTypes;
import org.flowable.common.engine.impl.interceptor.Command;
import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.entitylink.api.EntityLinkType;
import org.flowable.entitylink.api.history.HistoricEntityLink;

/**
 * @author Tijs Rademakers
 */
public class GetHistoricEntityLinkChildrenForCaseInstanceCmd implements Command<List<HistoricEntityLink>>, Serializable {

    private static final long serialVersionUID = 1L;
    
    protected String caseInstanceId;

    public GetHistoricEntityLinkChildrenForCaseInstanceCmd(String caseInstanceId) {
        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("caseInstanceId is required");
        }
        this.caseInstanceId = caseInstanceId;
    }

    @Override
    public List<HistoricEntityLink> execute(CommandContext commandContext) {
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        return cmmnEngineConfiguration.getEntityLinkServiceConfiguration().getHistoricEntityLinkService()
                .findHistoricEntityLinksByScopeIdAndScopeType(caseInstanceId, ScopeTypes.CMMN, EntityLinkType.CHILD);
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure a non-null caseInstanceId is supplied before constructing the command (check the variable/expression that provides it).
2. If the id comes from a lookup, fail earlier with a clear client-side error instead of passing null into the engine.
3. Use the history service API (e.g. historicEntityLink query APIs) with a validated id rather than building the command directly.

Example fix

// before
new GetHistoricEntityLinkChildrenForCaseInstanceCmd(request.get("caseInstanceId"));
// after
String caseInstanceId = request.get("caseInstanceId");
if (caseInstanceId == null) {
    throw new IllegalArgumentException("caseInstanceId must be provided");
}
new GetHistoricEntityLinkChildrenForCaseInstanceCmd(caseInstanceId);

if (caseInstanceId == null || caseInstanceId.isEmpty()) { throw new IllegalArgumentException("caseInstanceId must be provided"); }

boolean hasCaseInstanceId = s != null && !s.trim().isEmpty();

try { ... } catch (FlowableIllegalArgumentException e) { log.error("Missing argument: {}", e.getMessage()); throw new BadRequestException(e.getMessage()); }

When it happens

Trigger: Calling new GetHistoricEntityLinkChildrenForCaseInstanceCmd(null), or invoking an API path that passes a null caseInstanceId into this constructor (e.g. runtime/history service helpers resolving an id from a variable or map lookup that returned null).

Common situations: Developers pass the result of a lookup that returned null (e.g. map.get("caseId"), a request path variable not present), or confuse caseInstanceId with planItemInstanceId/taskId when wiring service calls.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• taskId is required
• caseInstanceId is required
• caseInstanceId is required
• taskId is required
• caseInstanceId is required

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