flowable/flowable-engine · critical · XMLException

BPMN XSD could not be found

Error message

BPMN XSD could not be found

What it means

BpmnXMLConverter.createSchema()/schema() lazily loads the BPMN 2.0 XSD from the classpath (BPMN_XSD resource). If the resource cannot be found on the classloader, the resulting Schema is null and an XMLException is thrown, since schema validation is impossible without the XSD.

Source

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

        Schema schema = createSchema();

        Validator validator = schema.newValidator();
        validator.validate(new StAXSource(xmlStreamReader));
    }

    protected Schema createSchema() throws SAXException {
        SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
        Schema schema = null;
        if (classloader != null) {
            schema = factory.newSchema(classloader.getResource(BPMN_XSD));
        }

        if (schema == null) {
            schema = factory.newSchema(BpmnXMLConverter.class.getClassLoader().getResource(BPMN_XSD));
        }

        if (schema == null) {
            throw new XMLException("BPMN XSD could not be found");
        }
        return schema;
    }

    public BpmnModel convertToBpmnModel(InputStreamProvider inputStreamProvider, boolean validateSchema, boolean enableSafeBpmnXml) {
        return convertToBpmnModel(inputStreamProvider, validateSchema, enableSafeBpmnXml, DEFAULT_ENCODING);
    }

    public BpmnModel convertToBpmnModel(InputStreamProvider inputStreamProvider, boolean validateSchema, boolean enableSafeBpmnXml, String encoding) {
        XMLInputFactory xif = XMLInputFactory.newInstance();

        if (xif.isPropertySupported(XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES)) {
            xif.setProperty(XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES, false);
        }

        if (xif.isPropertySupported(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES)) {
            xif.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the flowable-bpmn-converter jar contains the BPMN XSD resource (unzip and look for the xsd path referenced by BPMN_XSD)
2. Rebuild/re-download dependencies to replace a corrupted artifact
3. Fix maven-shade/assembly resource excludes or filtering so .xsd files are packaged
4. Ensure the classloader used can see converter jar resources (check app-server/OSGi classloading)
5. Add the full unmodified flowable-bpmn-converter dependency instead of copying classes manually

Example fix

// pom.xml — before (resource filtering breaks XSDs)
<resource><directory>src/main/resources</directory><filtering>true</filtering></resource>
// after — exclude binaries/xsd from filtering
<resource>
  <directory>src/main/resources</directory>
  <filtering>true</filtering>
  <excludes><exclude>**/*.xsd</exclude></excludes>
</resource>
<resource>
  <directory>src/main/resources</directory>
  <filtering>false</filtering>
  <includes><include>**/*.xsd</include></includes>
</resource>

String xsdPath = "org/flowable/bpmn/converter/BPMN20.xsd"; // value of BpmnXMLConverter.BPMN_XSD
if (BpmnXMLConverter.class.getClassLoader().getResource(xsdPath) == null) {
    throw new IllegalStateException("BPMN XSD missing from classpath; check packaging of flowable-bpmn-converter");
}

try {
    converter.convertToBpmnModel(inputStreamProvider, true, false);
} catch (XMLException e) {
    if (e.getMessage() != null && e.getMessage().contains("BPMN XSD could not be found")) {
        throw new IllegalStateException("Classpath is missing the BPMN XSD; fix jar packaging/classloading", e);
    }
    throw e;
}

When it happens

Trigger: Calling convertToBpmnModel/validateSchema (via schema()) when the classpath resource for the BPMN XSD is missing — typically a broken/partial flowable-bpmn-converter jar, shaded/fat-jar packaging that excluded .xsd resources, or a custom classloader that cannot see the resource.

Common situations: Fat-jar/uber-jar builds with resource filtering or excludes dropping XSD files; OSGi/app-server classloader isolation; corrupted maven artifacts; running with a stripped-down classpath.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• The bpmn 2.0 xml is not properly encoded
• CMND XSD could not be found
• resource '${resource}' not found
• Expected an activity behavior in flow node ${flowNode.getId(
• No outgoing sequence flow of element '${flowNode.getId()}' c

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