flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot find process definition for id

Error message

Cannot find process definition for id: ${processDefinitionId}

What it means

Flowable throws FlowableObjectNotFoundException when ProcessDefinitionUtil.getProcessDefinition cannot resolve the given processDefinitionId in GetFormDefinitionsForProcessDefinitionCmd. The id doesn't correspond to a deployed process definition, so form definitions cannot be derived. Message: 'Cannot find process definition for id: <id>'.

Solutions

  1. Verify the id via RepositoryService#createProcessDefinitionQuery#processDefinitionId before calling
  2. If you have the key instead, resolve the latest definition id first (processDefinitionQuery.processDefinitionKey(...).latestVersion())
  3. Redeploy the process definition if it was removed
  4. Confirm tenant/engine targeting matches where the definition was deployed

Example fix

// before
List<FormDefinition> forms = repositoryService.getFormDefinitionsForProcessDefinition(idOrKey);
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(idOrKey).singleResult();
if (pd == null) {
    pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey(idOrKey).latestVersion().singleResult();
}
List<FormDefinition> forms = (pd != null)
    ? repositoryService.getFormDefinitionsForProcessDefinition(pd.getId())
    : Collections.emptyList();
Defensive patterns

Strategy: try-catch

Validate before calling

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery().processDefinitionId(processDefinitionId).singleResult();
if (pd == null) throw new IllegalStateException("Unknown process definition: " + processDefinitionId);

Try / catch

try { ... } catch (FlowableObjectNotFoundException e) { /* definition missing — redeploy or resolve by key */ }

Prevention

When it happens

Trigger: RepositoryService.getFormDefinitionsForProcessDefinition(badId); querying with an id from an undeployed/removed deployment; using a process definition KEY where an ID is required (or vice versa).

Common situations: Deployments cleaned up (database cleanup jobs) while clients cache old ids; mixing definition key vs id vs version-specific id; multi-tenant setup where the id belongs to another tenant; schema mismatch between environments.

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

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetFormDefinitionsForProcessDefinitionCmd.java:56

/**
 * @author Yvo Swillens
 */
public class GetFormDefinitionsForProcessDefinitionCmd implements Command<List<FormDefinition>>, Serializable {

    private static final long serialVersionUID = 1L;
    protected String processDefinitionId;
    protected FormRepositoryService formRepositoryService;

    public GetFormDefinitionsForProcessDefinitionCmd(String processDefinitionId) {
        this.processDefinitionId = processDefinitionId;
    }

    @Override
    public List<FormDefinition> execute(CommandContext commandContext) {
        ProcessDefinition processDefinition = ProcessDefinitionUtil.getProcessDefinition(processDefinitionId);

        if (processDefinition == null) {
            throw new FlowableObjectNotFoundException("Cannot find process definition for id: " + processDefinitionId, ProcessDefinition.class);
        }

        BpmnModel bpmnModel = ProcessDefinitionUtil.getBpmnModel(processDefinitionId);

        if (bpmnModel == null) {
            throw new FlowableObjectNotFoundException("Cannot find bpmn model for process definition id: " + processDefinitionId, BpmnModel.class);
        }

        if (CommandContextUtil.getFormRepositoryService() == null) {
            throw new FlowableException("Form repository service is not available");
        }

        formRepositoryService = CommandContextUtil.getFormRepositoryService();
        List<FormDefinition> formDefinitions = getFormDefinitionsFromModel(bpmnModel, processDefinition);

        return formDefinitions;
    }

View on GitHub (pinned to d6d39ce1c6)