jhy/jsoup · error · Selector.SelectorParseException

:matchText is no longer supported. Use…

Error message

:matchText is no longer supported. Use Element#selectNodes(String, Class) with selector ::text and class TextNode instead.

What it means

jsoup's CSS selector parser no longer accepts the :matchText pseudo-selector; it was deprecated and now throws Selector.SelectorParseException when parsed. The replacement is Element#selectNodes(String, Class) using a ::text node selector with TextNode as the result class. This guard exists so old queries fail loudly instead of silently changing behavior.

Solutions

1. Replace the selector with Element#selectNodes("div ::text", TextNode.class) and iterate the returned TextNode list
2. If you need the containing elements, use select("div:contains(...)") or select text via Element#text()/#ownText()
3. Pin jsoup to an older version (<1.15) only as a temporary measure; the case is slated for removal

Example fix

// before
Elements els = doc.select("p:matchText");
// after
List<TextNode> textNodes = doc.selectNodes("p ::text", TextNode.class);

if (selector.contains(":matchText")) {
    List<TextNode> nodes = element.selectNodes(selector.replace(":matchText", " ::text"), TextNode.class);
}

boolean usesMatchText(String q) { return q != null && q.contains(":matchText"); }

try {
    Elements els = doc.select(query);
} catch (Selector.SelectorParseException e) {
    if (e.getMessage().contains(":matchText")) {
        List<TextNode> nodes = doc.selectNodes("div ::text", TextNode.class);
    } else { throw e; }
}

When it happens

Trigger: Calling Element.select(), Elements.select(), or Selector.select() with a query string containing ':matchText' (e.g. 'div:matchText'). Parsed in QueryParser.parsePseudoSelector, reached via parseSubclass.

Common situations: Upgrading jsoup from versions before 1.15.x where :matchText worked; queries copied from old Stack Overflow answers or legacy codebases that selected text nodes via :matchText.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Could not parse query
• Could not parse attribute query
• Could not parse nth-index
• The supplied URL, ' ', is malformed. Make sure it is an…
• You must execute the request before getting a response.

AI-assisted analysis of jhy/jsoup@9851ac5d9c (2026-09-08). Data as JSON: /api/errors/e88dc30fa4cb36bb. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/org/jsoup/select/QueryParser.java:259

                return new Evaluator.IsFirstChild();
            case "last-child":
                return new Evaluator.IsLastChild();
            case "first-of-type":
                return new Evaluator.IsFirstOfType();
            case "last-of-type":
                return new Evaluator.IsLastOfType();
            case "only-child":
                return new Evaluator.IsOnlyChild();
            case "only-of-type":
                return new Evaluator.IsOnlyOfType();
            case "empty":
                return new Evaluator.IsEmpty();
            case "blank":
                return new NodeEvaluator.BlankValue();
            case "root":
                return new Evaluator.IsRoot();
            case "matchText": {
                throw new Selector.SelectorParseException(":matchText is no longer supported. Use Element#selectNodes(String, Class) with selector ::text and class TextNode instead."); // todo remove this in 1.25.1
            }
            default:
                throw new Selector.SelectorParseException("Could not parse query '%s': unexpected token at '%s'", query, tq.remainder());
        }
    }

    // ::comment etc
    private Evaluator parseNodeSelector() {
        final String pseudo = tq.consumeCssIdentifier();
        inNodeContext = true;  // Enter node context

        Evaluator left;
        switch (pseudo) {
            case "node":
                left = new NodeEvaluator.InstanceType(Node.class, pseudo);
                break;
            case "leafnode":
                left = new NodeEvaluator.InstanceType(LeafNode.class, pseudo);

View on GitHub (pinned to 9851ac5d9c)