flowable/flowable-engine · error · FlowableObjectNotFoundException

Could not find a milestone instance with id '${milestoneInst

Error message

Could not find a milestone instance with id '${milestoneInstanceId}'.

What it means

FlowableObjectNotFoundException raised when no historic milestone instance exists with the given milestoneInstanceId. The REST endpoint queries cmmn-history/historic-milestone-instances/{id} and throws a 404-equivalent when singleResult() returns null. The missing type is HistoricMilestoneInstance.

Source

Thrown at modules/flowable-cmmn-rest/src/main/java/org/flowable/cmmn/rest/service/api/history/milestone/HistoricMilestoneInstanceResource.java:45

import io.swagger.annotations.Authorization;

/**
 * @author Tijs Rademakers
 * @author Dennis Federico
 */
@RestController
@Api(tags = {"History Milestone"}, authorizations = {@Authorization(value = "basicAuth")})
public class HistoricMilestoneInstanceResource extends HistoricMilestoneInstanceBaseResource {

    @ApiOperation(value = "Get a historic milestone instance by id", tags = {"History Milestone"}, nickname = "getHistoricMilestoneInstanceById")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Indicates that the historic milestone instances could be found."),
            @ApiResponse(code = 404, message = "Indicates that the historic milestone instances could not be found.")})
    @GetMapping(value = "/cmmn-history/historic-milestone-instances/{milestoneInstanceId}", produces = "application/json")
    public HistoricMilestoneInstanceResponse getMilestoneInstance(@ApiParam(name = "milestoneInstanceId") @PathVariable String milestoneInstanceId) {
        HistoricMilestoneInstance milestoneInstance = historyService.createHistoricMilestoneInstanceQuery().milestoneInstanceId(milestoneInstanceId).singleResult();
        if (milestoneInstance == null) {
            throw new FlowableObjectNotFoundException("Could not find a milestone instance with id '" + milestoneInstanceId + "'.", HistoricMilestoneInstance.class);
        }
        
        if (restApiInterceptor != null) {
            restApiInterceptor.accessHistoryMilestoneInfoById(milestoneInstance);
        }
        
        return restResponseFactory.createHistoricMilestoneInstanceResponse(milestoneInstance);
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Confirm the milestoneInstanceId is correct (check for typos or ids from another environment).
Catch FlowableObjectNotFoundException and map it to HTTP 404 in your REST error handler.
Check history cleanup settings - historic instances may have been removed by the cleaner.
Verify the CMMN history level retains milestone instances.
Query the list endpoint with filters to see which milestone instance ids actually exist.

Example fix

// before
HistoricMilestoneInstanceResponse r = client.getMilestone(id);
// after
try {
    HistoricMilestoneInstanceResponse r = client.getMilestone(id);
} catch (FlowableObjectNotFoundException e) {
    return ResponseEntity.notFound().build();
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    HistoricMilestoneInstanceResponse m = getMilestone(id);
} catch (FlowableObjectNotFoundException e) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body("Milestone not found");
}

Prevention

Treat any singleResult-by-id REST lookup as optional; always handle 404.
Track ids as opaque strings, never reconstruct them.
Be aware of history cleanup retention windows.
Confirm ids came from the same engine/tenant database.

When it happens

Trigger: GET /cmmn-history/historic-milestone-instances/{milestoneInstanceId} with an id that does not match any historic milestone instance row (already purged, never existed, or wrong engine/datasource).

Common situations: History cleanup job removed old milestone instances; caller stored ids from a different database/tenant; milestone never completed so no historic record was written; history level set below the required level.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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