What causes "Error exporting diagram" in flowable/flowable-engine?

Check the process-definition resource still exists: GET /repository/deployments/{deploymentId}/resourcelist and verify the diagram/BPMN resource.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Error exporting diagram

Error message

Error exporting diagram

What it means

When a process instance diagram is requested, the REST layer converts the diagram resource stream to a PNG byte array. If any exception occurs while reading the resource (closed/broken stream, missing diagram resource, IO problem), getProcessInstanceDiagram wraps it in FlowableIllegalArgumentException('Error exporting diagram').

Source

Thrown at modules/flowable-rest/src/main/java/org/flowable/rest/service/api/runtime/process/ProcessInstanceDiagramResource.java:81

    @GetMapping(value = "/runtime/process-instances/{processInstanceId}/diagram")
    public ResponseEntity<byte[]> getProcessInstanceDiagram(@ApiParam(name = "processInstanceId") @PathVariable String processInstanceId, HttpServletResponse response) {
        ProcessInstance processInstance = getProcessInstanceFromRequest(processInstanceId);

        ProcessDefinition pde = repositoryService.getProcessDefinition(processInstance.getProcessDefinitionId());

        if (pde != null && pde.hasGraphicalNotation()) {
            BpmnModel bpmnModel = repositoryService.getBpmnModel(pde.getId());
            ProcessDiagramGenerator diagramGenerator = processEngineConfiguration.getProcessDiagramGenerator();
            InputStream resource = diagramGenerator.generateDiagram(bpmnModel, "png", runtimeService.getActiveActivityIds(processInstance.getId()), Collections.emptyList(),
                    processEngineConfiguration.getActivityFontName(), processEngineConfiguration.getLabelFontName(),
                    processEngineConfiguration.getAnnotationFontName(), processEngineConfiguration.getClassLoader(), 1.0,processEngineConfiguration.isDrawSequenceFlowNameWithNoLabelDI());

            HttpHeaders responseHeaders = new HttpHeaders();
            responseHeaders.set("Content-Type", "image/png");
            try {
                return new ResponseEntity<>(IOUtils.toByteArray(resource), responseHeaders, HttpStatus.OK);
            } catch (Exception e) {
                throw new FlowableIllegalArgumentException("Error exporting diagram", e);
            }

        } else {
            throw new FlowableIllegalArgumentException("Process instance with id '" + processInstance.getId() + "' has no graphical notation defined.");
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the process-definition resource still exists: GET /repository/deployments/{deploymentId}/resourcelist and verify the diagram/BPMN resource.
Redeploy the original BPMN (with diagram info) or restart the instance from a valid definition, then retry the diagram call.
Inspect the cause exception in server logs — usually an IO or DB problem reading ACT_GE_BYTEARRAY.

Example fix

// before (client): assume diagram always available
def diagram = get("/runtime/process-instances/" + id + "/diagram")
// after: guard and redeploy/refresh definition if missing
if (!definitionResourceExists(instance.getProcessDefinitionId())) {
    redeployOriginalBpmn(processKey);
}
def diagram = get("/runtime/process-instances/" + id + "/diagram")

Defensive patterns

Strategy: try-catch

Try / catch

try {
    byte[] png = restClient.getDiagram(processInstanceId);
} catch (HttpStatusCodeException e) {
    if (e.getResponseBodyAsString().contains("Error exporting diagram")) {
        // inspect cause in server logs; verify deployment resource still exists, then retry
    }
}

Prevention

Avoid undeploying/cascading-deleting deployments with running instances.
Monitor DB connectivity; diagram export reads the resource blob.
Cache diagram images to reduce repeated stream reads.

When it happens

Trigger: GET /runtime/process-instances/{id}/diagram on an instance whose definition does have a graphical notation, but the resource stream cannot be read — e.g. the process-definition resource was undeployed/redeployed after the instance started, or an IO error while streaming. Thrown at ProcessInstanceDiagramResource.java:81.

Common situations: Definitions redeployed/undeployed while old instances are still running; database resource blob cleaned up; cluster with shared DB but missing deployment resources on one node; temporary DB connection issues during stream read.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — 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/fbbd6aee74d04a97. Report an issue: GitHub.