json-path/JsonPath · error · JsonPathException

Options AS_PATH_LIST and ALWAYS_RETURN_LIST are not allowed

Error message

Options AS_PATH_LIST and ALWAYS_RETURN_LIST are not allowed when using path functions!

What it means

When a JsonPath uses functions (e.g. .length(), .min(), .max()), the library evaluates the function to a single computed value; wrapping that in AS_PATH_LIST (return paths instead of values) or ALWAYS_RETURN_LIST (always wrap in a list) is meaningless, so JsonPathException is thrown. With suppressExceptions enabled it quietly returns null/empty array instead.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/JsonPath.java:177

     * the {@link JsonProvider}
     *
     * @param jsonObject    a container Object
     * @param configuration configuration to use
     * @param <T>           expected return type
     * @return object(s) matched by the given path
     */
    @SuppressWarnings("unchecked")
    public <T> T read(Object jsonObject, Configuration configuration) {
        boolean optAsPathList = configuration.containsOption(AS_PATH_LIST);
        boolean optAlwaysReturnList = configuration.containsOption(Option.ALWAYS_RETURN_LIST);
        boolean optSuppressExceptions = configuration.containsOption(Option.SUPPRESS_EXCEPTIONS);

        if (path.isFunctionPath()) {
            if (optAsPathList || optAlwaysReturnList) {
                if (optSuppressExceptions) {
                    return (T) (path.isDefinite() ? null : configuration.jsonProvider().createArray());
                }
                throw new JsonPathException("Options " + AS_PATH_LIST + " and " + ALWAYS_RETURN_LIST + " are not allowed when using path functions!");
            }
            EvaluationContext evaluationContext = path.evaluate(jsonObject, jsonObject, configuration);
            if (optSuppressExceptions && evaluationContext.getPathList().isEmpty()) {
                return (T) (path.isDefinite() ? null : configuration.jsonProvider().createArray());
            }
            return evaluationContext.getValue(true);
        } else if (optAsPathList) {
            EvaluationContext evaluationContext = path.evaluate(jsonObject, jsonObject, configuration);
            if (optSuppressExceptions && evaluationContext.getPathList().isEmpty()) {
                return (T) configuration.jsonProvider().createArray();
            }
            return (T) evaluationContext.getPath();
        } else {
            EvaluationContext evaluationContext = path.evaluate(jsonObject, jsonObject, configuration);
            if (optSuppressExceptions && evaluationContext.getPathList().isEmpty()) {
                if (optAlwaysReturnList) {
                    return (T) configuration.jsonProvider().createArray();
                } else {

View on GitHub (pinned to 62a4c9f0f6)

Solutions

Remove AS_PATH_LIST/ALWAYS_RETURN_LIST from the Configuration used for function paths.
Build a separate Configuration without those options for function reads.
If list-wrapping is needed, wrap the result yourself: Arrays.asList(JsonPath.read(json, "$.items.length()")).
Check path.isFunctionPath() before choosing the configuration.

Example fix

// before
Configuration conf = Configuration.builder().options(Option.ALWAYS_RETURN_LIST).build();
int len = JsonPath.using(conf).read(json, "$.items.length()");
// after
int len = JsonPath.read(json, "$.items.length()");

Defensive patterns

Strategy: validation

Validate before calling

if (path.isFunctionPath() && (conf.getOptions().contains(Option.AS_PATH_LIST) || conf.getOptions().contains(Option.ALWAYS_RETURN_LIST))) {
    conf = Configuration.builder().build(); // drop conflicting options
}

Try / catch

try {
    return JsonPath.using(conf).read(json, functionPath);
} catch (JsonPathException e) {
    if (e.getMessage().contains("not allowed when using path functions")) {
        return JsonPath.read(json, functionPath); // retry without options
    }
    throw e;
}

Prevention

Keep two configurations: one plain for function paths, one with options otherwise.
Check isFunctionPath() before selecting a configuration.
Do not globally enable ALWAYS_RETURN_LIST across all reads.

When it happens

Trigger: JsonPath.read(json, "$.items.length()", Configuration.builder().options(Option.AS_PATH_LIST).build()) or the same with Option.ALWAYS_RETURN_LIST — any read where path.isFunctionPath() and either option is set.

Common situations: Developers reusing a shared Configuration with ALWAYS_RETURN_LIST for all reads, then reading a function path like $.array.length(); or using path-list mode to introspect paths and hitting a function path.

Related errors

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