flowable/flowable-engine · error · FlowableIllegalArgumentException

The case instance id is mandatory, but '

Error message

The case instance id is mandatory, but '

What it means

The CaseInstanceClaimCmd constructor throws FlowableIllegalArgumentException when caseInstanceId is null or an empty string (length < 1). Claiming a case instance requires a concrete instance id; the command fails at construction so an invalid command never reaches execution.

Source

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

import org.flowable.common.engine.api.FlowableException;
import org.flowable.common.engine.api.FlowableIllegalArgumentException;
import org.flowable.common.engine.api.FlowableObjectNotFoundException;
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.identitylink.api.IdentityLinkType;
import org.flowable.identitylink.service.impl.persistence.entity.IdentityLinkEntity;

public class CaseInstanceClaimCmd implements Command<Void>, Serializable {

    private static final long serialVersionUID = 1L;

    private final String caseInstanceId;
    private final String userId;

    public CaseInstanceClaimCmd(String caseInstanceId, String userId) {
        if (caseInstanceId == null || caseInstanceId.length() < 1) {
            throw new FlowableIllegalArgumentException("The case instance id is mandatory, but '" + caseInstanceId + "' has not been provided.");
        }

        this.caseInstanceId = caseInstanceId;
        this.userId = userId;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        CaseInstanceEntityManager caseInstanceEntityManager = CommandContextUtil.getCaseInstanceEntityManager(commandContext);
        CaseInstanceEntity caseInstanceEntity = caseInstanceEntityManager.findById(caseInstanceId);
        if (caseInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("No case instance found for id = '" + caseInstanceId + "'.", CaseInstance.class);
        }

        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        if (userId != null) {
            List<IdentityLinkEntity> identityLinks = cmmnEngineConfiguration.getIdentityLinkServiceConfiguration()
                    .getIdentityLinkService().findIdentityLinksByScopeIdAndType(caseInstanceId, ScopeTypes.CMMN);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure caseInstanceId is non-null and non-empty before calling the claim API
2. Validate request inputs (e.g. @NotBlank on the id field) at the API boundary
3. Trim ids from external sources and reject blank values early

Example fix

// before
if (request.getCaseInstanceId() != null) {
    cmmnRuntimeService.claimCaseInstance(request.getCaseInstanceId(), user); // empty string still fails
}
// after
if (request.getCaseInstanceId() != null && !request.getCaseInstanceId().trim().isEmpty()) {
    cmmnRuntimeService.claimCaseInstance(request.getCaseInstanceId().trim(), user);
}

if (caseInstanceId == null || caseInstanceId.trim().isEmpty()) throw new IllegalArgumentException("caseInstanceId is required");

boolean isValidId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    cmmnRuntimeService.claimCaseInstance(caseId, userId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("A case instance id must be provided");
}

When it happens

Trigger: Calling cmmnTaskService/cmmnRuntimeService claim APIs with a null or "" caseInstanceId — e.g. claim(caseInstanceId, userId) where the id came from an unset request parameter or an empty path variable.

Common situations: REST handlers forwarding empty path segments; form submissions missing the hidden case instance id field; beans where the id property was never populated before invoking the service.

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

• type is required when adding a new case instance identity li
• userId and groupId cannot both be null
• No case instance found for id = '
• caseInstanceId is required
• taskId is required

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