flowable/flowable-engine · error · XMLException

The bpmn 2.0 xml is not properly encoded

Error message

The bpmn 2.0 xml is not properly encoded

What it means

BpmnXMLConverter.convertToBpmnModel wraps UnsupportedEncodingException into XMLException('The bpmn 2.0 xml is not properly encoded'). The parser could not create an XML stream reader for the input using the requested character encoding (e.g. invalid or unavailable encoding name, or bytes not matching the declared encoding).

Source

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

        }
        
        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_DTD)) {
            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, "");
        }
        
        if (xif.isPropertySupported(XMLConstants.ACCESS_EXTERNAL_SCHEMA)) {
            xif.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, "");
        }

        if (validateSchema) {
            try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {
                if (!enableSafeBpmnXml) {
                    validateModel(inputStreamProvider);
                } else {
                    validateModel(new FlowableXMLStreamReader(xif.createXMLStreamReader(in)));
                }
            } catch (UnsupportedEncodingException e) {
                throw new XMLException("The bpmn 2.0 xml is not properly encoded", e);
            } catch(XMLStreamException e){
                throw new XMLException("Error while reading the BPMN 2.0 XML", e);
            } catch(Exception e){
                throw new XMLException(e.getMessage(), e);
            }
        }
        // The input stream is closed after schema validation
        try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {
            // XML conversion
            return convertToBpmnModel(xif.createXMLStreamReader(in));
        } catch (UnsupportedEncodingException e) {
            throw new XMLException("The bpmn 2.0 xml is not properly encoded", e);
        } catch (XMLStreamException e) {
            throw new XMLException("Error while reading the BPMN 2.0 XML", e);
        } catch (IOException e) {
            throw new XMLException(e.getMessage(), e);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Validate the encoding name passed to convertToBpmnModel; use standard names like 'UTF-8'
  2. Call the convertToBpmnModel overload that uses DEFAULT_ENCODING instead of a custom encoding
  3. Re-save/re-export the BPMN XML file as UTF-8
  4. Check the XML declaration encoding in the BPMN file matches the actual byte encoding
  5. Catch XMLException around convertToBpmnModel and inspect the cause for the exact encoding problem

Example fix

// before
converter.convertToBpmnModel(inputStreamProvider, true, false, "UTF8");
// after
converter.convertToBpmnModel(inputStreamProvider, true, false, "UTF-8");
Defensive patterns

Strategy: validation

Validate before calling

private static boolean isValidEncoding(String enc) {
    try {
        return enc == null || !java.nio.charset.Charset.isSupported(enc);
    } catch (Exception e) { return false; }
}
// use only when isValidEncoding returns false:
// throw new IllegalArgumentException("Unsupported encoding: " + enc);

Try / catch

try {
    BpmnModel model = converter.convertToBpmnModel(provider, validate, safeBpmn, encoding);
} catch (XMLException e) {
    if (e.getCause() instanceof java.io.UnsupportedEncodingException) {
        throw new IllegalArgumentException("Bad encoding '" + encoding + "' for BPMN XML", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling convertToBpmnModel(...) with an InputStream whose declared/requested encoding (inputStream encoding or DEFAULT_ENCODING parameter) is unsupported or misspelled, causing xif.createXMLStreamReader(in) to throw UnsupportedEncodingException.

Common situations: Passing a custom encoding string with a typo (e.g. 'utf-8 ' with whitespace or 'UTF8' variants) to the convertToBpmnModel overload with explicit encoding; XML documents with a wrong encoding declaration feeding a stream that can't be decoded; deployments where BPMN XML was saved with a broken/unknown charset.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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