jhy/jsoup · error · ValidationException

msg (String.format with args)

Error message

msg (String.format with args)

What it means

The varargs overload of Validate.fail throws a ValidationException whose message is String.format(msg, args), enabling parameterized failure messages. It signals a failed precondition/validation in jsoup with formatted detail about the offending values.

Solutions

1. Parse the formatted message to identify the exact bad value cited.
2. Correct the argument at the call site to satisfy the precondition.
3. Add your own bounds/shape checks before calling the jsoup API.
4. Update jsoup if the violated check reflects an outdated library assumption.

Example fix

// before
doc.childNode(i); // i out of range -> formatted fail
// after
if (i >= 0 && i < doc.childNodeSize()) doc.childNode(i);

if (index < 0 || index >= node.childNodeSize()) throw new IndexOutOfBoundsException("index " + index + " out of range");

try { /* jsoup operation */ } catch (org.jsoup.helper.ValidationException e) { log.warn("jsoup validation failed: {}", e.getMessage()); }

When it happens

Trigger: A jsoup API calling Validate.fail(format, args...) when validation fails — same class of precondition violations as the single-message fail, but the message includes interpolated values (indices, names, counts) that failed the check.

Common situations: Off-by-one or out-of-range indices passed to document accessors; mismatched collection sizes when composing nodes; usage patterns that break documented invariants where the message reports the actual bad value.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Must be true
• Must be false
• Pattern syntax error:
• Pattern complexity error
• Pattern syntax error:

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

Appendix: source

Thrown at src/main/java/org/jsoup/helper/Validate.java:206

    /**
     Cause a failure, but return false so it can be used in an assert statement.
     @param msg message to output.
     @return false, always
     @throws IllegalStateException if we reach this state
     */
    static boolean assertFail(String msg) {
        fail(msg);
        return false;
    }

    /**
     Cause a failure.
     @param msg message to output.
     @param args the format arguments to the msg
     @throws IllegalStateException if we reach this state
     */
    public static void fail(String msg, Object... args) {
        throw new ValidationException(String.format(msg, args));
    }
}

View on GitHub (pinned to 9851ac5d9c)