What causes "Batch with id '${batchId}' does not have a batch document." in flowable/flowable-engine?

Ensure the batch was created with a document (the value passed to the batch creation call); recreate the batch with a document if it is required.

flowable/flowable-engine · error · FlowableObjectNotFoundException

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

Error message

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

What it means

GET /management/batches/{batchId}/content fetches the batch's document JSON through managementService.getBatchDocument. The batch itself exists, but no document was stored for it, so the endpoint throws FlowableObjectNotFoundException with String.class as the missing type. Flowable only stores a batch document when one is provided at batch creation time.

Source

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

    public BatchSummaryResponse getBatchSummary(@ApiParam(name = "batchId") @PathVariable String batchId) {
        getBatchById(batchId);
        BatchSummary batchSummary = managementService.getBatchSummary(batchId);
        return restResponseFactory.createBatchSummaryResponse(batchSummary);
    }

    @ApiOperation(value = "Get the batch document", tags = { "Batches" })
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Indicates the requested batch was found and the batch document has been returned. The response contains the raw batch document and always has a Content-type of application/json."),
            @ApiResponse(code = 404, message = "Indicates the requested batch was not found or the job does not have a batch document. Status-description contains additional information about the error.")
    })
    @GetMapping("/management/batches/{batchId}/batch-document")
    public String getBatchDocument(@ApiParam(name = "batchId") @PathVariable String batchId, HttpServletResponse response) {
        Batch batch = getBatchById(batchId);

        String batchDocument = managementService.getBatchDocument(batchId);

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

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

    @ApiOperation(value = "Delete a batch", tags = { "Batches" }, nickname = "deleteBatch", code = 204)
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Indicates the batch was found and has been deleted. Response-body is intentionally empty."),
            @ApiResponse(code = 404, message = "Indicates the requested batch was not found.")
    })
    @DeleteMapping("/management/batches/{batchId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteJob(@ApiParam(name = "batchId") @PathVariable String batchId) {
        Batch batch = getBatchById(batchId);
        if (restApiInterceptor != null) {
            restApiInterceptor.deleteBatch(batch);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure the batch was created with a document (the value passed to the batch creation call); recreate the batch with a document if it is required.
For built-in migration batches, confirm the batch is a migration batch — other batch types may legitimately have no document.
Treat the 404 as 'no document stored' in the client and proceed without content or use a default.
Inspect the ACT_RU_BATCH DOC column for the id to confirm the document was never stored.

Example fix

// before
String doc = managementService.getBatchDocument(batchId); // throws if no document stored
// after
Batch batch = managementService.createBatchQuery().batchId(batchId).singleResult();
String doc = managementService.getBatchDocument(batchId);
if (doc == null) { doc = "{}"; /* batch has no stored document */ }

Defensive patterns

Strategy: try-catch

Validate before calling

Batch batch = managementService.createBatchQuery().batchId(batchId).singleResult();
// existence of the batch does not guarantee a document; pre-check only narrows the failure

Try / catch

try { doc = client.getBatchDocument(batchId); }
catch (FlowableObjectNotFoundException e) { doc = null; /* batch stored without a document */ }

Prevention

Create batches with a document when clients will fetch content.
Only assume a document exists for batch types that always store one (e.g. process-migration batches).
Check the batch table's document column when debugging.
Handle the 404 as 'no content' rather than a hard failure.

When it happens

Trigger: Requesting the document of a batch that was created without a document payload, or after the document column was cleared.

Common situations: Batches created by custom code that omitted the document; migrations where the document column is null; clients assuming every batch has content (e.g. migration batches usually do, ad-hoc ones may not).

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