flowable/flowable-engine · error · FlowableException

Error retrieving the JAXB binding definitions

Error message

Error retrieving the JAXB binding definitions

What it means

During importFrom, after locating the JAXB binding resource, an IOException while reading it (or otherwise retrieving binding definitions) is wrapped and rethrown as FlowableException 'Error retrieving the JAXB binding definitions'. It indicates the resource was found but could not be read.

Solutions

  1. Verify the jar/resource integrity (checksum, re-deploy the flowable-cxf jar) and redeploy the application.
  2. Check read permissions and accessibility of the jar file containing the binding resource.
  3. Log/print the URL from getResources() and try reading it directly to pinpoint the failing source.
  4. If the resource is a remote URL, ensure network availability and reasonable connection settings.

Example fix

// before
URL u = cl.getResource(JAXB_BINDINGS_RESOURCE); // unreadable/corrupt source
// after
try (InputStream in = u.openStream()) { /* verify readable at startup */ }
// and re-deploy a verified flowable-cxf jar if the stream fails
Defensive patterns

Strategy: try-catch

Validate before calling

Enumeration<URL> urls = Thread.currentThread().getContextClassLoader().getResources("jaxb-bindings.xml");
while (urls.hasMoreElements()) {
    try (InputStream in = urls.nextElement().openStream()) { in.read(); } // verify readable
}

Try / catch

try {
    importer.importFrom(wsdlUrl);
} catch (FlowableException e) {
    if (e.getMessage().contains("Error retrieving the JAXB binding definitions")) {
        // verify jar integrity, permissions, and redeploy
    }
}

Prevention

When it happens

Trigger: IOException thrown while opening/reading the JAXB binding URL from the classloader — corrupted jar, unreadable file, closed/defunct URL connection, or I/O failure reading the resource stream during DynamicClientFactory setup.

Common situations: Corrupted or partially downloaded jar in the app server; network/classloader resource (remote jar in JBoss/fuse) becoming unavailable; filesystem permission problems on exploded deployments; stale hot-deploy artifacts.

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

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

Appendix: source

Thrown at modules/flowable-cxf/src/main/java/org/flowable/engine/impl/webservice/CxfWSDLImporter.java:143

                Definition def = wsdlManager.getDefinition(url);
                WSDLServiceBuilder builder = new WSDLServiceBuilder(bus);
                List<ServiceInfo> services = builder.buildServices(def);

                for (ServiceInfo service : services) {
                    WSService wsService = this.importService(service);
                    this.wsServices.put(this.namespace + wsService.getName(), wsService);
                }

                if (def != null && def.getTypes() != null) {
                    this.importTypes(def.getTypes());
                }
            } else {
                throw new FlowableException("The JAXB binding definitions are not found for flowable-cxf: " + JAXB_BINDINGS_RESOURCE);
            }
        } catch (WSDLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            throw new FlowableException("Error retrieving the JAXB binding definitions", e);
        }
    }

    protected WSService importService(ServiceInfo service) {
        String name = service.getName().getLocalPart();
        String location = "";

        for (EndpointInfo endpoint : service.getEndpoints()) {
            location = endpoint.getAddress();
        }

        WSService wsService = new WSService(this.namespace + name, location, this.wsdlLocation);
        for (OperationInfo operation : service.getInterface().getOperations()) {
            WSOperation wsOperation = this.importOperation(operation, wsService);
            wsService.addOperation(wsOperation);

            this.wsOperations.put(this.namespace + operation.getName().getLocalPart(), wsOperation);
        }

View on GitHub (pinned to d6d39ce1c6)