flowable/flowable-engine · error · FlowableIllegalArgumentException

caseInstanceId is required

Error message

caseInstanceId is required

What it means

GetHistoricEntityLinkChildrenWithSameRootAsCaseInstanceCmd retrieves historic entity links for a case instance that share the same root entity. Its constructor throws FlowableIllegalArgumentException when caseInstanceId is null since the root-scoped query is meaningless without it.

Source

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

import org.flowable.cmmn.engine.CmmnEngineConfiguration;
import org.flowable.cmmn.engine.impl.util.CommandContextUtil;
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 Filip Hrisafov
 */
public class GetHistoricEntityLinkChildrenWithSameRootAsCaseInstanceCmd implements Command<List<HistoricEntityLink>> {
    
    protected String caseInstanceId;

    public GetHistoricEntityLinkChildrenWithSameRootAsCaseInstanceCmd(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()
                .findHistoricEntityLinksWithSameRootScopeForScopeIdAndScopeType(caseInstanceId, ScopeTypes.CMMN, EntityLinkType.CHILD);
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid non-null caseInstanceId when constructing the command.
2. Check the source of the id (variable, map, request) and fail with a clear message before engine invocation.
3. Confirm you are using the right id type (case instance id, not plan item or task id).

Example fix

// before
new GetHistoricEntityLinkChildrenWithSameRootAsCaseInstanceCmd(ctx.getVariable("caseInstanceId"));
// after
String caseInstanceId = (String) ctx.getVariable("caseInstanceId");
Objects.requireNonNull(caseInstanceId, "caseInstanceId must be provided");
new GetHistoricEntityLinkChildrenWithSameRootAsCaseInstanceCmd(caseInstanceId);

Objects.requireNonNull(caseInstanceId, "caseInstanceId must be provided");

boolean validId = id instanceof String && !((String) id).isEmpty();

try { ... } catch (FlowableIllegalArgumentException e) { log.warn("Missing caseInstanceId"); return Collections.emptyList(); }

When it happens

Trigger: Constructing the command with a null caseInstanceId, or a service wrapper that resolves the id from a nullable variable/expression and forwards null.

Common situations: Root/parent hierarchy lookups where the caller confused caseInstanceId with root entity id, or a null returned by a previous engine query.

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

• caseInstanceId is required
• taskId 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/a0bcf25666b2e6d8. Report an issue: GitHub.