json-path/JsonPath · error · IllegalArgumentException

String.format(message, values)

Error message

String.format(message, values)

What it means

Utils.notEmpty(chars, message, values...) is an internal precondition guard: it throws IllegalArgumentException (with the formatted message) when the given CharSequence is null or has length 0. It is Jayway JsonPath's way of asserting that required string arguments (paths, keys, etc.) are non-empty before proceeding.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/Utils.java:443

    /**
     * <p>Validate that the specified argument character sequence is
     * neither {@code null} nor a length of zero (no characters);
     * otherwise throwing an exception with the specified message.
     * <p/>
     * <pre>Validate.notEmpty(myString, "The string must not be empty");</pre>
     *
     * @param <T>     the character sequence type
     * @param chars   the character sequence to check, validated not null by this method
     * @param message the {@link String#format(String, Object...)} exception message if invalid, not null
     * @param values  the optional values for the formatted exception message, null array not recommended
     * @return the validated character sequence (never {@code null} method for chaining)
     * @throws NullPointerException     if the character sequence is {@code null}
     * @throws IllegalArgumentException if the character sequence is empty
     */
    public static <T extends CharSequence> T notEmpty(T chars, String message, Object... values) {
        if (chars == null || chars.length() == 0) {
            throw new IllegalArgumentException(String.format(message, values));
        }
        return chars;
    }


    //---------------------------------------------------------
    //
    // Converters
    //
    //---------------------------------------------------------
    public static String toString(Object o) {
        if (null == o) {
            return null;
        }
        return o.toString();
    }

    private Utils() {

View on GitHub (pinned to 62a4c9f0f6)

Solutions

  1. Ensure the argument passed to JsonPath APIs is a non-null, non-empty string before calling.
  2. Check the code producing the path/key (config, env var, split result) and filter out empty values.
  3. Provide a sensible default path/key when the dynamic value is blank.

Example fix

// before
String path = System.getenv("JSON_PATH"); // may be null/empty
DocumentContext ctx = JsonPath.parse(json).read(path); // IllegalArgumentException
// after
String path = System.getenv("JSON_PATH");
if (path == null || path.isEmpty()) path = "$";
DocumentContext ctx = JsonPath.parse(json).read(path);
Defensive patterns

Strategy: validation

Validate before calling

if (path == null || path.isEmpty()) {
    throw new IllegalArgumentException("JsonPath string must be non-null and non-empty");
}
String key = configKey != null ? configKey.trim() : "";
if (key.isEmpty()) { /* substitute default or fail fast */ }

Try / catch

try {
    return JsonPath.compile(path);
} catch (IllegalArgumentException e) {
    // empty/null path argument rejected by Utils.notEmpty
    throw new IllegalArgumentException("Empty or null path supplied to JsonPath", e);
}

Prevention

When it happens

Trigger: Any internal call site validating a CharSequence argument with Utils.notEmpty(...) where the caller passes null or "" — e.g. calling JsonPath.compile(""), Path with an empty path string, put()/renameKey()/add() with an empty key, or an empty criteria value passed into filter builders.

Common situations: Paths or keys built dynamically from config/environment variables that resolve to empty strings; splitting a comma-separated path list that yields empty entries; empty JSON pointer fragments passed through APIs.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of json-path/JsonPath@62a4c9f0f6 (2026-09-11). Data as JSON: /api/errors/29ee9584a292ae6c. Report an issue: GitHub.