flowable/flowable-engine · error · FlowableObjectNotFoundException

Batch part with id '${batchPartId}' does not have a batch pa

Error message

Batch part with id '${batchPartId}' does not have a batch part document.

What it means

GET /management/batch-parts/{batchPartId}/content returns the batch part's stored document via managementService.getBatchPartDocument. The batch part row exists (getBatchPartById succeeded), but its document column is null, so the controller throws FlowableObjectNotFoundException typed to String.class. Flowable stores no document for batch parts unless one was set when the batch was created/started.

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/management/BatchPartResource.java:67

    @GetMapping(value = "/management/batch-parts/{batchPartId}", produces = "application/json")
    public BatchPartResponse getBatchPart(@ApiParam(name = "batchPartId") @PathVariable String batchPartId) {
        BatchPart batchPart = getBatchPartById(batchPartId);
        return restResponseFactory.createBatchPartResponse(batchPart);
    }
    
    @ApiOperation(value = "Get the batch part document", tags = { "Batches" })
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Indicates the requested batch part was found and the batch part document has been returned. The response contains the raw batch part document and always has a Content-type of application/json."),
            @ApiResponse(code = 404, message = "Indicates the requested batch part was not found or the job does not have a batch part document. Status-description contains additional information about the error.")
    })
    @GetMapping("/management/batch-parts/{batchPartId}/batch-part-document")
    public String getBatchPartDocument(@ApiParam(name = "batchPartId") @PathVariable String batchPartId, HttpServletResponse response) {
        BatchPart batchPart = getBatchPartById(batchPartId);

        String batchPartDocument = managementService.getBatchPartDocument(batchPartId);

        if (batchPartDocument == null) {
            throw new FlowableObjectNotFoundException("Batch part with id '" + batchPart.getId() + "' does not have a batch part document.", String.class);
        }

        response.setContentType("application/json");
        return batchPartDocument;
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the batch part's type: only parts created with a document payload will return one; skip the document call when not applicable.
Set a batch document when creating the batch (e.g. via runtimeService/process-driven batch creation that supplies the document JSON) if one is required.
Verify the document column in the DB table for that part id is genuinely null (then this is expected data, not a bug).
Handle the 404 response in the REST client and fall back to a default/empty document.

Example fix

// before
String doc = managementService.getBatchPartDocument(partId); // NPEs/404 when absent
// after
BatchPart part = managementService.createBatchPartQuery().batchPartId(partId).singleResult();
String doc = managementService.getBatchPartDocument(partId);
if (doc == null) { doc = "{}"; /* default document */ }

Defensive patterns

Strategy: try-catch

Validate before calling

BatchPart part = managementService.createBatchPartQuery().batchPartId(batchPartId).singleResult();
// no API to pre-check the document; treat null document as expected

Try / catch

try { doc = client.getBatchPartDocument(partId); }
catch (FlowableObjectNotFoundException e) { doc = null; /* part has no document */ }

Prevention

Only request documents for batch types known to store one.
Default to an empty JSON document when the fetch 404s.
Verify document storage in the DB when a document is expected.
Read the batch-creation code to confirm a document was supplied.

When it happens

Trigger: Requesting the document of a batch part that was never given a document (e.g. a batch started without a batch document, or a part type that carries no payload).

Common situations: Custom batch types created without a document; assuming every part has JSON content; copying document-fetch logic from batch to batch-part where only the batch has a document.

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/2a5630632112346b. Report an issue: GitHub.