flowable/flowable-engine · error · FlowableObjectNotFoundException

Could not find a process instance with id '" + processInstan

Error message

Could not find a process instance with id '" + processInstanceId + "'.

What it means

A helper on HistoricProcessInstanceBaseResource queries historyService.createHistoricProcessInstanceQuery().processInstanceId(id).singleResult(); when the result is null it throws FlowableObjectNotFoundException. It means no historic process instance with that id exists in the history tables.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/history/HistoricProcessInstanceBaseResource.java:304

        }
        
        return responseList;
    }
    
    protected HistoricProcessInstance getHistoricProcessInstanceFromRequest(String processInstanceId) {
        HistoricProcessInstance processInstance = getHistoricProcessInstanceFromRequestWithoutAccessCheck(processInstanceId);

        if (restApiInterceptor != null) {
            restApiInterceptor.accessHistoryProcessInfoById(processInstance);
        }
        
        return processInstance;
    }

    protected HistoricProcessInstance getHistoricProcessInstanceFromRequestWithoutAccessCheck(String processInstanceId) {
        HistoricProcessInstance processInstance = historyService.createHistoricProcessInstanceQuery().processInstanceId(processInstanceId).singleResult();
        if (processInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a process instance with id '" + processInstanceId + "'.", HistoricProcessInstance.class);
        }

        return processInstance;
    }

    protected void addVariables(HistoricProcessInstanceQuery processInstanceQuery, List<QueryVariable> variables) {
        for (QueryVariable variable : variables) {
            if (variable.getVariableOperation() == null) {
                throw new FlowableIllegalArgumentException("Variable operation is missing for variable: " + variable.getName());
            }
            if (variable.getVariableOperation() != QueryVariableOperation.EXISTS && variable.getVariableOperation() != QueryVariableOperation.NOT_EXISTS) {
                if (variable.getValue() == null) {
                    throw new FlowableIllegalArgumentException("Variable value is missing for variable: " + variable.getName());
                }
            }

            boolean nameLess = variable.getName() == null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Confirm the processInstanceId by listing /history/historic-process-instances first
  2. Check the engine's history level is high enough (audit/full) to record the instance
  3. Catch FlowableObjectNotFoundException (HTTP 404) and handle 'no history' explicitly
  4. Verify history cleanup configuration is not deleting the instance you need

Example fix

// before
curl /flowable-rest/history/historic-process-instances/wrong-id

// after
// find the correct id first
curl "/flowable-rest/history/historic-process-instances?processDefinitionKey=myProcess"
// then
curl /flowable-rest/history/historic-process-instances/<correctId>
Defensive patterns

Strategy: validation

Validate before calling

const list = await fetch(`${BASE}/history/historic-process-instances?processInstanceId=${id}`).then(r => r.json());
if (!list.data || list.data.length === 0) throw new Error(`No history for process instance ${id}`);

Type guard

function isValidProcessInstanceId(id) { return typeof id === 'string' && id.length > 0; }

Try / catch

try { return await getHistoricProcessInstance(id); } catch (e) { if (e.status === 404) return null; throw e; }

Prevention

When it happens

Trigger: GET /history/historic-process-instances/{processInstanceId} (and related sub-resources) with an id that never ran or whose history was purged.

Common situations: History level set to 'none' or 'audit' pruning instances; cleanup jobs deleting old history; using a runtime-only id before any history row exists or after engine migration.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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