flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceId is required

Error message

processInstanceId is required

What it means

The GetHistoricEntityLinkChildrenForProcessInstanceCmd constructor requires a processInstanceId and throws FlowableIllegalArgumentException when it is null. Entity links relate a process instance to its child entities (sub-processes, tasks), so the id is mandatory to perform the historic query.

Solutions

1. Provide a valid, non-null historic process instance id before constructing the command.
2. Validate the id at the call site and skip the query when absent.
3. Confirm you obtained the id from the historic process instance (not a deleted runtime one) via runtimeService/historyService.

Example fix

// before
historyService.findHistoricEntityLinkChildrenForProcessInstance(instanceId);
// after
if (instanceId == null) {
    throw new IllegalArgumentException("Historic process instance id must be set");
}
historyService.findHistoricEntityLinkChildrenForProcessInstance(instanceId);

Objects.requireNonNull(processInstanceId, "processInstanceId is required to query historic entity link children");

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

When it happens

Trigger: new GetHistoricEntityLinkChildrenForProcessInstanceCmd(null), typically when the historic process instance's id is read from a variable or optional lookup that resolved to null.

Common situations: Querying entity links for a process instance that has already been fully purged from history; passing runtimeExecutionId instead of processInstanceId; null returned by HistoricProcessInstance.getId() after a failed query.

Related errors

• processInstanceId is required
• processInstanceId is required
• taskId is required
• taskId is required
• taskId or processInstanceId is required

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetHistoricEntityLinkChildrenForProcessInstanceCmd.java:37

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 Tijs Rademakers
 */
public class GetHistoricEntityLinkChildrenForProcessInstanceCmd implements Command<List<HistoricEntityLink>>, Serializable {

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

    public GetHistoricEntityLinkChildrenForProcessInstanceCmd(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()
                .findHistoricEntityLinksByScopeIdAndScopeType(processInstanceId, ScopeTypes.BPMN, EntityLinkType.CHILD);
    }

}

View on GitHub (pinned to d6d39ce1c6)