Repository navigation
NodeTraversor revisits nodes created in head() causing infinite loop when mutating (since 1.21.2) #2472
Description
Since 1.21.2, this code will enter an infinite loop because of 967306f .
public class Main {
public static void main(String[] args) {
Document document = Jsoup.parseBodyFragment("<div>a</div>");
document.traverse(new NodeVisitor() {
@Override
public void head(Node node, int depth) {
if (node instanceof TextNode) {
Node newNode = new TextNode("b");
node.replaceWith(newNode);
// or
// node.before(newNode);
// node.remove();
// or
// node.after(newNode);
// node.remove();
}
}
});
}
}
head() visits new nodes created in head() and it causes infinite loop.
It might be OK to revisit a new node to deal with it.
But this behaviour have some problems:
- you can't use
replaceWith()inhead() - you can use
before()withoutremove(), but not withremove()
I'm not sure if this is a bug or not. If isn't, please close this.
Activity
jhy commentedon Mar 6, 2026
Thanks for the clear report and regression analysis! Yes, this was a bug.
The change in 1.21.2 for #2355 made the traversor re-enter
head()on whatever node ended up in the current sibling position after areplaceWith(),before()+remove(), orafter()+remove(). In cases like your example, that could loop indefinitely.I've fixed that by refactoring the traversal path into a clearer forward-cursor walk.
head()is called once for the node at the current cursor position; if that position is replaced, traversal continues from there without callinghead()on the replacement again. That fixes the loop and makes the mutation path much easier to reason about.I also added regression tests and tightened the Javadocs to spell out the supported contract:
head()tail()Please go ahead and test with a snapshot install and confirm that it's fixed for you.
Refactor NodeTraversor.traverse to have a clearer state machine impl
jhy commentedon Mar 6, 2026
(Reworked the structural mod detection to support more cases like
unwrapetc, in a96388d)kna commentedon Mar 6, 2026
@jhy
Thank you so much! I'll check it with my code next week.
Update CHANGES.md for NodeTraversor fixes
jhy commentedon Mar 8, 2026
Just to detail this a bit more, it ended up being a bit broader than just the loop fix.
NodeTraversornow has a clearer and more capable mutation contract duringhead(): current-node edits likeremove(),replaceWith(), andunwrap()recover from the correct cursor position, exposed children and later siblings may still be visited when they are still ahead of the traversal, and traversal stays within the original root subtree.That makes single-pass DOM rewrite visitors more predictable and easier to reason about, beyond fixing the 1.21.2 regression that could loop when replacing the current node.
kna commentedon Mar 9, 2026
@jhy
I've checked jsoup on master branch with my code and it works well. Thank you.