json-path/JsonPath · error · InvalidPathException

Use bracket notion ['my prop'] if your property contains bla

Error message

Use bracket notion ['my prop'] if your property contains blank characters. position: 

What it means

Property names in dot notation may not contain spaces. When readPropertyOrFunctionToken encounters a SPACE while scanning a property name, compilation aborts with InvalidPathException telling the user to switch to bracket notation ['my prop'].

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/internal/path/PathCompiler.java:194

    }

    //
    // fooBar or fooBar()
    //
    private boolean readPropertyOrFunctionToken(PathTokenAppender appender) {
        if (path.currentCharIs(OPEN_SQUARE_BRACKET) || path.currentCharIs(WILDCARD) || path.currentCharIs(PERIOD) || path.currentCharIs(SPACE)) {
            return false;
        }
        int startPosition = path.position();
        int readPosition = startPosition;
        int endPosition = 0;

        boolean isFunction = false;

        while (path.inBounds(readPosition)) {
            char c = path.charAt(readPosition);
            if (c == SPACE) {
                throw new InvalidPathException("Use bracket notion ['my prop'] if your property contains blank characters. position: " + path.position());
            }
            else if (c == PERIOD || c == OPEN_SQUARE_BRACKET) {
                endPosition = readPosition;
                break;
            }
            else if (c == OPEN_PARENTHESIS) {
                isFunction = true;
                endPosition = readPosition;
                break;
            }
            readPosition++;
        }
        if (endPosition == 0) {
            endPosition = path.length();
        }


        List<Parameter> functionParameters = null;

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Use bracket notation with quotes: `$.['first name']` or `$['first name']`.
2. Prefer bracket notation whenever keys are dynamic or may contain spaces/special characters.
3. Normalize the document keys (strip spaces) upstream if you control the data.

Example fix

// before
JsonPath.read(json, "$.first name");
// after
JsonPath.read(json, "$['first name']");

String toBracketNotation(String path) {
    return path.replaceAll("\\.([^.\\[\]]*\\s[^.\\[\]]*)", "['$1']");
}

try {
    return JsonPath.read(json, path);
} catch (InvalidPathException e) {
    throw new IllegalArgumentException("Property with spaces? Use ['prop name']: " + path, e);
}

When it happens

Trigger: Paths like `$.first name`, `$['a'].my prop`, or reading JSON with keys containing spaces using dot notation, e.g. `$.address line 1`.

Common situations: JSON produced from CSV headers or form fields with spaces in key names; XML-derived keys like `<first name>` mapped to JSON; users unaware dot notation can't express such keys.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Failed to parse ArrayIndexOperation:
• Failed to parse token in ArrayIndexOperation:
• Path must start with '$' or '@'
• Path must not end with a '.
• Character '.' on position is not valid.

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