What causes "Error writing BPMN XML" in flowable/flowable-engine?

Inspect the logged stack trace ('Error writing BPMN XML') for the real cause.

flowable/flowable-engine · error · XMLException

Error writing BPMN XML

Error message

Error writing BPMN XML

What it means

convertToXML(BpmnModel, OutputStream) catches any Exception raised while writing the model to StAX XMLStreamWriter and wraps it as XMLException("Error writing BPMN XML"). This is the serialization direction: the in-memory BpmnModel could not be written out as BPMN 2.0 XML.

Source

Thrown at modules/flowable-bpmn-converter/src/main/java/org/flowable/bpmn/converter/BpmnXMLConverter.java:609

            }

            BPMNDIExport.writeBPMNDI(model, xtw);

            // end definitions root element
            xtw.writeEndElement();
            xtw.writeEndDocument();

            xtw.flush();

            outputStream.close();

            xtw.close();

            return outputStream.toByteArray();

        } catch (Exception e) {
            LOGGER.error("Error writing BPMN XML", e);
            throw new XMLException("Error writing BPMN XML", e);
        }
    }

    protected void createXML(FlowElement flowElement, BpmnModel model, XMLStreamWriter xtw) throws Exception {

        if (flowElement instanceof SubProcess subProcess) {

            if (flowElement instanceof Transaction) {
                xtw.writeStartElement(ELEMENT_TRANSACTION);
            } else if (flowElement instanceof AdhocSubProcess) {
                xtw.writeStartElement(ELEMENT_ADHOC_SUBPROCESS);
            } else {
                xtw.writeStartElement(ELEMENT_SUBPROCESS);
            }

            xtw.writeAttribute(ATTRIBUTE_ID, subProcess.getId());
            if (StringUtils.isNotEmpty(subProcess.getName())) {
                if (!(options.isSaveElementNameWithNewLineInExtensionElement() && BpmnXMLUtil.containsNewLine(subProcess.getName()))) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the logged stack trace ('Error writing BPMN XML') for the real cause.
Ensure the target OutputStream is open, writable, and not closed before conversion finishes.
Validate model element names/IDs/strings for illegal XML characters before calling convertToXML.
Check disk space or stream capacity if writing to a file or in-memory buffer.

Example fix

// before
OutputStream out = Files.newOutputStream(path); out.close(); // closed early
converter.convertToXML(model, out);
// after
try (OutputStream out = Files.newOutputStream(path)) {
    converter.convertToXML(model, out);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Sanity-check the model and target stream before serializing
if (model == null || model.getMainProcess() == null) {
    throw new IllegalStateException("Nothing to serialize: empty BpmnModel");
}
if (!outCanAcceptMore) throw new IOException("Target stream unavailable");

Try / catch

try {
    byte[] xml = converter.convertToXML(model, out);
} catch (XMLException e) {
    log.error("BPMN serialization failed; cause:", e.getCause());
    throw e;
}

Prevention

Keep the OutputStream open until convertToXML returns (use try-with-resources at the call site)
Check disk space when writing to files
Sanitize programmatically-set element names/IDs for illegal XML characters

When it happens

Trigger: Calling convertToXML(model, out) where a converter's createXML throws (I/O error on the underlying OutputStream, XMLStreamException, or an exception thrown while serializing a particular flow element).

Common situations: Writing to a closed/full OutputStream, disk-full when serializing to a file stream, or a model containing elements that fail during XML generation (e.g. illegal characters in names/IDs from programmatic model edits).

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

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