flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceId is required

Error message

processInstanceId is required

What it means

The GetHistoricEntityLinkParentsForProcessInstanceCmd constructor requires a processInstanceId and throws FlowableIllegalArgumentException when it is null. Parent entity links describe the ancestor chain (parent process/case instances) of a process instance and cannot be resolved without the id.

Solutions

1. Pass the process instance id from HistoricProcessInstance.getId() after confirming the instance exists.
2. Guard for null at each step of the hierarchy traversal and stop when the id is absent (root reached).
3. Use the process instance id, not the execution id, when constructing the command.

Example fix

// before
String parentId = current.getParentId();
historyService.findHistoricEntityLinkParentsForProcessInstance(parentId);
// after
if (current.getParentId() == null) {
    return; // reached the root process instance
}
historyService.findHistoricEntityLinkParentsForProcessInstance(current.getParentId());

if (processInstanceId == null) { return Collections.emptyList(); /* root instance: no parents */ }

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

When it happens

Trigger: new GetHistoricEntityLinkParentsForProcessInstanceCmd(null) — commonly when walking a hierarchy and a root process instance (which has no parent references) yields a null parent id, or a lookup returned null.

Common situations: Traversing parent entity links upward and passing a null for the root; process instance purged from history; mixing up execution id with 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/f814632f85b801c1. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetHistoricEntityLinkParentsForProcessInstanceCmd.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 Javier Casal
 */
public class GetHistoricEntityLinkParentsForProcessInstanceCmd implements Command<List<HistoricEntityLink>>, Serializable {

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

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

}

View on GitHub (pinned to d6d39ce1c6)