flowable/flowable-engine · error · FlowableException

Error while reading process diagram image.

Error message

Error while reading process diagram image.

What it means

getDiagramBoundsFromImage reads the process diagram image via ImageIO.read to compute diagram bounds. If the stream cannot be read (IOException), Flowable wraps it in this FlowableException. Note ImageIO.read returns null (not an exception) for unsupported formats — that failure surfaces later as an NPE.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/diagram/ProcessDiagramLayoutFactory.java:192

        DiagramNode diagramBounds = new DiagramNode("BPMNDiagram");
        diagramBounds.setX(minX);
        diagramBounds.setY(minY);
        diagramBounds.setWidth(maxX - minX);
        diagramBounds.setHeight(maxY - minY);
        return diagramBounds;
    }

    protected DiagramNode getDiagramBoundsFromImage(InputStream imageStream) {
        return getDiagramBoundsFromImage(imageStream, 0, 0);
    }

    protected DiagramNode getDiagramBoundsFromImage(InputStream imageStream, int offsetTop, int offsetBottom) {
        BufferedImage image;
        try {
            image = ImageIO.read(imageStream);
        } catch (IOException e) {
            throw new FlowableException("Error while reading process diagram image.", e);
        }
        DiagramNode diagramBoundsImage = getDiagramBoundsFromImage(image, offsetTop, offsetBottom);
        return diagramBoundsImage;
    }

    protected DiagramNode getDiagramBoundsFromImage(BufferedImage image, int offsetTop, int offsetBottom) {
        int width = image.getWidth();
        int height = image.getHeight();

        Map<Integer, Boolean> rowIsWhite = new TreeMap<>();
        Map<Integer, Boolean> columnIsWhite = new TreeMap<>();

        for (int row = 0; row < height; row++) {
            if (!rowIsWhite.containsKey(row)) {
                rowIsWhite.put(row, true);
            }
            if (row <= offsetTop || row > image.getHeight() - offsetBottom) {
                rowIsWhite.put(row, true);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the image InputStream is fresh, open, and fully readable before passing it in
2. Re-fetch the diagram resource from the repository instead of reusing a consumed stream
3. Verify the image file is a valid, non-truncated PNG/JPEG/GIF that ImageIO can decode
4. Check the wrapped IOException cause for the underlying I/O problem (network, permissions, disk)

Example fix

// before
byte[] cached = imageBytes; factory.getProcessDiagramLayout(xml, new ByteArrayInputStream(cached));

// after: re-read resource bytes fresh from the repository
ResourceEntity res = repositoryService.getResource(deploymentId, resourceName);
factory.getProcessDiagramLayout(xmlStream, new ByteArrayInputStream(res.getBytes()));

if (imageStream == null || imageStream.available() <= 0) {
    throw new IllegalArgumentException("Diagram image stream is empty or closed");
}
BufferedImage img = ImageIO.read(new BufferedInputStream(imageStream)); // also detect unsupported formats (null result)

try {
    layout = factory.getProcessDiagramLayout(xmlStream, imageStream);
} catch (FlowableException e) {
    if (e.getMessage().equals("Error while reading process diagram image.")) {
        // re-open/re-fetch the image stream and retry once
    }
}

When it happens

Trigger: getBpmnProcessDiagramLayout (or the recursive/diagramBoundsImage paths) receives an image stream that throws IOException when read — closed stream, network failure mid-read, truncated file.

Common situations: Passing an already-consumed InputStream; a diagram URL/stream that broke mid-download; corrupted image files in the deployment; unsupported image formats (which yield null from ImageIO.read instead).

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Error reading image stream
• Error while reading process diagram image.
• Error converting resource stream
• could not get byte array from resource '${resourceName}'
• Error while generating case image

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