flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceId is required

Error message

processInstanceId is required

What it means

GetHistoricEntityLinkChildrenWithSameRootAsProcessInstanceCmd requires a processInstanceId and throws FlowableIllegalArgumentException when null. This command queries historic entity links that share the same root scope as the given process instance, so the id is mandatory.

Solutions

1. Supply a non-null process instance id obtained from the runtime or historic process instance object.
2. Validate before constructing the command and skip/return empty on null.
3. Verify the id type: this API expects the process instance id, not execution or task ids.

Example fix

// before
historyService.findHistoricEntityLinksWithSameRootAsProcessInstance(piId);
// after
if (piId == null) {
    return Collections.emptyList();
}
historyService.findHistoricEntityLinksWithSameRootAsProcessInstance(piId);

if (processInstanceId == null) { return Collections.emptyList(); }

try {
    return historyService.findHistoricEntityLinksWithSameRootAsProcessInstance(processInstanceId);
} catch (FlowableIllegalArgumentException e) {
    return Collections.emptyList();
}

When it happens

Trigger: new GetHistoricEntityLinkChildrenWithSameRootAsProcessInstanceCmd(null), typically from a null result of a process-instance lookup or an uninitialized variable at the caller.

Common situations: Navigating process-instance hierarchies where a parent/child instance id was never set; querying after history cleanup removed the instance; passing a task id or execution id instead of the process instance id.

Related errors

• processInstanceId is required
• processInstanceId is required
• taskId is required
• taskId is required
• A process instance id is required, but the provided id '" +…

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

Appendix: source

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

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.engine.impl.cfg.ProcessEngineConfigurationImpl;
import org.flowable.engine.impl.util.CommandContextUtil;
import org.flowable.entitylink.api.EntityLinkType;
import org.flowable.entitylink.api.history.HistoricEntityLink;

/**
 * @author Filip Hrisafov
 */
public class GetHistoricEntityLinkChildrenWithSameRootAsProcessInstanceCmd implements Command<List<HistoricEntityLink>> {

    protected String processInstanceId;

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

    @Override
    public List<HistoricEntityLink> execute(CommandContext commandContext) {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        return processEngineConfiguration.getEntityLinkServiceConfiguration().getHistoricEntityLinkService()
                .findHistoricEntityLinksWithSameRootScopeForScopeIdAndScopeType(processInstanceId, ScopeTypes.BPMN, EntityLinkType.CHILD);
    }

}

View on GitHub (pinned to d6d39ce1c6)