flowable/flowable-engine · error · FlowableObjectNotFoundException

No plan item instance found for id ${planItemInstanceId}

Error message

No plan item instance found for id ${planItemInstanceId}

What it means

Thrown by SetLocalVariableAsyncCmd.execute when the plan item instance id is non-null but no PlanItemInstanceEntity exists for it. Flowable throws FlowableObjectNotFoundException (typed PlanItemInstanceEntity) and neither the variable nor the async job is created.

Source

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

    public SetLocalVariableAsyncCmd(String planItemInstanceId, String variableName, Object variableValue) {
        this.planItemInstanceId = planItemInstanceId;
        this.variableName = variableName;
        this.variableValue = variableValue;
    }
    
    @Override
    public Void execute(CommandContext commandContext) {
        if (planItemInstanceId == null) {
            throw new FlowableIllegalArgumentException("planItemInstanceId is null");
        }
        if (variableName == null) {
            throw new FlowableIllegalArgumentException("variable name is null");
        }
     
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        PlanItemInstanceEntity planItemInstanceEntity = cmmnEngineConfiguration.getPlanItemInstanceEntityManager().findById(planItemInstanceId);
        if (planItemInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("No plan item instance found for id " + planItemInstanceId, PlanItemInstanceEntity.class);
        }
        
        addVariable(true, planItemInstanceEntity.getCaseInstanceId(), planItemInstanceEntity.getId(), variableName, variableValue, planItemInstanceEntity.getTenantId(), 
                cmmnEngineConfiguration.getVariableServiceConfiguration().getVariableService());
        createSetAsyncVariablesJob(planItemInstanceEntity, cmmnEngineConfiguration);
        
        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Re-fetch the plan item instance (planItemInstanceQuery().planItemInstanceId(id)) right before setting the variable
2. Verify the plan item is still active; completed plan items no longer accept local variables
3. Check for concurrent case termination in your workflow and handle it
4. Catch FlowableObjectNotFoundException and fail gracefully with a not-found response

Example fix

// before
cmmnRuntimeService.setLocalVariableAsync(planItemInstanceId, variableName, value);
// after
PlanItemInstance pii = cmmnRuntimeService.createPlanItemInstanceQuery().planItemInstanceId(planItemInstanceId).singleResult();
if (pii != null) {
    cmmnRuntimeService.setLocalVariableAsync(planItemInstanceId, variableName, value);
} else {
    logger.warn("Plan item instance {} no longer exists", planItemInstanceId);
}

PlanItemInstance pii = cmmnRuntimeService.createPlanItemInstanceQuery().planItemInstanceId(planItemInstanceId).singleResult();
if (pii == null) { throw new NotFoundException("Plan item instance not found: " + planItemInstanceId); }

try {
    cmmnRuntimeService.setLocalVariableAsync(planItemInstanceId, variableName, value);
} catch (FlowableObjectNotFoundException e) {
    logger.warn("Plan item instance {} disappeared before variable write", planItemInstanceId);
    throw new NotFoundException(e.getMessage(), e);
}

When it happens

Trigger: Calling setLocalVariableAsync with an id for a plan item instance that does not exist or has already been removed.

Common situations: Setting a variable on a plan item whose stage already completed/terminated; id captured before a case rollback; race condition where the plan item ended between lookup and variable set; wrong environment database.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• No plan item instance found for id ${planItemInstanceId}
• Cannot find case instance for id ${caseInstanceId}
• Cannot find plan item instance for id ${planItemInstanceId}
• Cannot find task with id ${taskId}
• Cannot find case instance with id

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