flowable/flowable-engine · error · CmmnXMLException

The CMMN 1.1 xml is not properly encoded

Error message

The CMMN 1.1 xml is not properly encoded

What it means

CmmnXmlConverter.convertToCmmnModel opens the source stream with the given encoding to run schema validation. If the JVM cannot support that encoding (UnsupportedEncodingException), it throws CmmnXMLException 'The CMMN 1.1 xml is not properly encoded'.

Source

Thrown at modules/flowable-cmmn-converter/src/main/java/org/flowable/cmmn/converter/CmmnXmlConverter.java:187

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

        if (encoding == null) {
            encoding = DEFAULT_ENCODING;
        }

        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 CmmnXMLException("The CMMN 1.1 xml is not properly encoded", e);
            } catch (XMLStreamException e) {
                throw new CmmnXMLException("Error while reading the CMMN 1.1 XML", e);
            } catch (Exception e) {
                throw new CmmnXMLException(e.getMessage(), e);
            }
        }
        // The input stream is closed after schema validation
        try (InputStreamReader in = new InputStreamReader(inputStreamProvider.getInputStream(), encoding)) {
            // XML conversion
            return convertToCmmnModel(xif.createXMLStreamReader(in));
        } catch (UnsupportedEncodingException e) {
            throw new CmmnXMLException("The CMMN 1.1 xml is not properly encoded", e);
        } catch (XMLStreamException e) {
            throw new CmmnXMLException("Error while reading the CMMN 1.1 XML", e);
        } catch (IOException e) {
            throw new CmmnXMLException(e.getMessage(), e);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Use a standard charset such as 'UTF-8' for the CMMN XML and converter encoding
  2. Validate the encoding string with Charset.isSupported(...) before conversion
  3. Re-encode the XML file to UTF-8
  4. Check the wrapped UnsupportedEncodingException cause for the offending charset name

Example fix

// before
converter.setEncoding("UTF-8-Strict");
// after
converter.setEncoding("UTF-8");
Defensive patterns

Strategy: validation

Validate before calling

String enc = converterEncoding; // e.g. from config
if (!Charset.isSupported(enc)) throw new IllegalArgumentException("Unsupported encoding for CMMN XML: " + enc);

Try / catch

try { converter.convertToCmmnModel(provider); } catch (CmmnXMLException e) { throw new IllegalArgumentException("Bad encoding for CMMN XML: " + e.getCause().getMessage(), e); }

Prevention

When it happens

Trigger: Calling CmmnXmlConverter.convertToCmmnModel with an encoding string unsupported by the JVM (e.g. a typo'd charset name on the configured encoding) while creating the InputStreamReader/XMLStreamReader for validation.

Common situations: Setting an invalid encoding on the converter or deployment; moving apps to a JVM with a reduced charset set; passing encoding from config with typos like 'utf-8 ' or 'UTF8-' variants unsupported.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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