flowable/flowable-engine · error · FlowableException

Error reading batch part

Error message

Error reading batch part 

What it means

Thrown by GetProcessInstanceMigrationBatchResultCmd.convertFromBatchPart when parsing a process instance migration batch part's JSON result fails with a JacksonException. The batch part document could not be read, so the command aborts instead of returning a partially populated BatchPartResult. The original Jackson message is discarded, which makes this error opaque unless the batch part document itself is inspected.

Solutions

1. Query the batch part table (ACT_RU_BATCH_PART / FlowableBatchPart) for the offending batchPart.getId() and inspect/repair its result JSON document.
2. Delete the corrupt batch part (or the whole batch) and re-run the process instance migration to regenerate clean batch parts.
3. Check for a Flowable version mismatch between the engine that wrote the batch parts and the one reading them; align versions or migrate the batch data.
4. If you control the code, log the caught JacksonException (or chain it: new FlowableException(msg, e)) to expose the underlying parse failure.

Example fix

// before
} catch (JacksonException e) {
    throw new FlowableException("Error reading batch part " + batchPart.getId());
}
// after
} catch (JacksonException e) {
    throw new FlowableException("Error reading batch part " + batchPart.getId(), e);
}

// verify the batch part is readable before requesting the result
BatchPart part = managementService.getBatchPart(batchPartId); // non-null means part exists
if (part == null) { throw new IllegalStateException("Batch part " + batchPartId + " missing/corrupt"); }

try {
    migrationService.getBatchResult(batchId);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Error reading batch part")) {
        // inspect/repair batch part document or re-run the migration
    }
}

When it happens

Trigger: Calling the migration batch result API (ProcessInstanceMigrationService.getBatchResult / runtimeService batch result command) when a batch part document in the batch part table is missing, corrupt, or contains JSON that does not match the expected structure (e.g. missing/invalid batch result fields).

Common situations: Corrupted ACT_RU_BATCH_PART rows after a database restore or manual data migration; a Flowable version upgrade changing the batch result JSON shape while old parts remain; direct manipulation of the batch part JSON document; deserialization of a result containing unexpected node types (e.g. an array where an object is expected).

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• batch entity not found for id
• batch has to be provided
• Batch with id ' ' does not have a batch document.
• batchId is null
• batchSearchKey is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetProcessInstanceMigrationBatchResultCmd.java:108

        partResult.setResult(batchPart.getStatus());
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration();
        if (ProcessInstanceBatchMigrationResult.RESULT_FAIL.equals(batchPart.getStatus()) && 
                batchPart.getResultDocumentJson(processEngineConfiguration.getEngineCfgKey()) != null) {
            
            try {
                JsonNode resultNode = objectMapper.readTree(batchPart.getResultDocumentJson(processEngineConfiguration.getEngineCfgKey()));
                if (resultNode.has(BATCH_RESULT_MESSAGE_LABEL)) {
                    String resultMessage = resultNode.get(BATCH_RESULT_MESSAGE_LABEL).asString();
                    partResult.setMigrationMessage(resultMessage);
                }
                
                if (resultNode.has(BATCH_RESULT_STACKTRACE_LABEL)) {
                    String resultStacktrace = resultNode.get(BATCH_RESULT_STACKTRACE_LABEL).asString();
                    partResult.setMigrationStacktrace(resultStacktrace);
                }
                
            } catch (JacksonException e) {
                throw new FlowableException("Error reading batch part " + batchPart.getId());
            }
        }
        
        return partResult;
    }
}

View on GitHub (pinned to d6d39ce1c6)