flowable/flowable-engine · error · FlowableException

Could not evaluate xpath expression

Error message

Could not evaluate xpath expression ${xpathExpression}

What it means

XpathBasedInboundEventKeyDetector extracts the event definition key from an inbound XML payload by compiling and evaluating a configured XPath expression expected to return a single Node. Any failure — malformed XPath, evaluation errors, or a non-node result (null cast failure) — is wrapped in a FlowableException that includes the xpathExpression.

Solutions

1. Validate the XPath expression syntax and test it against a real payload (e.g. in an XPath tester) before wiring the detector
2. Ensure the payload actually contains the element targeted by the XPath, including required namespaces
3. Adjust the XPath to be namespace-aware or prefix-free as appropriate for the document
4. Wrap inbound event processing with error handling and fall back to a header-based or default key detector for malformed payloads

Example fix

// before
detector.setXpathExpression("/event/key"); // payload uses namespace: no match -> NPE -> wrapped
// after
detector.setXpathExpression("//*[local-name()='key']");

// pre-validate against a sample payload
Node n = (Node) XPathFactory.newInstance().newXPath()
    .compile(xpathExpression).evaluate(sampleDocument, XPathConstants.NODE);
if (n == null) throw new IllegalStateException("XPath matches no node in sample payload");

try {
    String key = detector.detectEventDefinitionKey(payload);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Could not evaluate xpath")) {
        // log payload + xpathExpression, route to dead-letter / default key handling
    }
}

When it happens

Trigger: Calling detectEventDefinitionKey(Document) when the configured xpathExpression is syntactically invalid, or when it evaluates to no node (null) so the cast to Node fails, while processing an inbound XML event payload.

Common situations: XPath configured against a different XML schema than the actual payload (element renamed, namespace prefixes missing); wrong XPath dialect; test fixtures with payloads lacking the key element.

Related errors

• Could not evaluate xpath expression
• Could not deserialize event to xml
• The channel xml key detection value was not found for the…
• The channel xml tenant detection value was not found for…
• XML serialization failed for

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

Appendix: source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/keydetector/XpathBasedInboundEventKeyDetector.java:42

/**
 * @author Joram Barrez
 */
public class XpathBasedInboundEventKeyDetector implements InboundEventKeyDetector<Document> {

    protected String xpathExpression;

    public XpathBasedInboundEventKeyDetector(String xpathExpression) {
        this.xpathExpression = xpathExpression;
    }

    @Override
    public String detectEventDefinitionKey(Document payload) {
        try {
            XPath xPath = XPathFactory.newInstance().newXPath();
            Node result = (Node) xPath.compile(xpathExpression).evaluate(payload, XPathConstants.NODE);
            return result.getTextContent();
        } catch (Exception e) {
            throw new FlowableException("Could not evaluate xpath expression " + xpathExpression, e);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)