json-path/JsonPath · error · IllegalStateException

Parser is not in KEY_NAME, VALUE_STRING, or VALUE_NUMBER sta

Error message

Parser is not in KEY_NAME, VALUE_STRING, or VALUE_NUMBER state

What it means

JakartaMappingProvider's JSON-P parser adapter exposes getString() only when the underlying parser is positioned on a key name, a string value, or a number value (which is returned as its string form). If the parser sits on any other event (START_ARRAY, START_OBJECT, VALUE_TRUE, VALUE_FALSE, VALUE_NULL, etc.), the adapter throws this IllegalStateException instead of returning a meaningless value. It indicates the caller pulled a string at the wrong point in the JSON event stream.

Source

Thrown at json-path/src/main/java/com/jayway/jsonpath/spi/mapper/JakartaMappingProvider.java:473

                            state = Event.END_OBJECT;
                        }
                    }
                }
            }
            return state;
        }

        @Override
        public String getString() {
            switch (state) {
            case KEY_NAME:
                return ((JsonObjectScope) scope).getKey();
            case VALUE_STRING:
                return ((JsonString) scope.getValue()).getString();
            case VALUE_NUMBER:
                return ((JsonNumber) scope.getValue()).toString();
            default:
                throw new IllegalStateException("Parser is not in KEY_NAME, VALUE_STRING, or VALUE_NUMBER state");
            }
        }

        @Override
        public boolean isIntegralNumber() {
            if (state == Event.VALUE_NUMBER) {
                return ((JsonNumber) scope.getValue()).isIntegral();
            }
            throw new IllegalStateException("Target json value must a number, not " + state);
        }

        @Override
        public int getInt() {
            if (state == Event.VALUE_NUMBER) {
                return ((JsonNumber) scope.getValue()).intValue();
            }
            throw new IllegalStateException("Target json value must a number, not " + state);
        }

View on GitHub (pinned to 62a4c9f0f6)

Solutions

1. Check the current event with hasNext()/next() and only call getString() when the event is KEY_NAME, VALUE_STRING, or VALUE_NUMBER
2. Use the accessor matching the current state (getInt/getLong/getBigDecimal for VALUE_NUMBER, isIntegralNumber for numeric checks)
3. If this happens inside custom mapping logic, inspect what Configuration.mappingConfiguration() provider is set and ensure code paths match the adapter's streaming contract

Example fix

// before
String s = parser.getString(); // may throw if event is START_ARRAY
// after
Event ev = parser.next();
String s = (ev == Event.VALUE_STRING || ev == Event.KEY_NAME || ev == Event.VALUE_NUMBER)
    ? parser.getString()
    : null;

// before reading
Event ev = /* last event returned by parser.next() */;
boolean canReadString = (ev == Event.KEY_NAME || ev == Event.VALUE_STRING || ev == Event.VALUE_NUMBER);

boolean isStringReadable(Event ev) {
    return ev == Event.KEY_NAME || ev == Event.VALUE_STRING || ev == Event.VALUE_NUMBER;
}

try {
    String s = parser.getString();
} catch (IllegalStateException e) {
    // wrong parser state: re-check the current Event and use the proper accessor
}

When it happens

Trigger: Calling getString() on the adapter returned by JakartaMappingProvider when the current parser state (Event) is not KEY_NAME, VALUE_STRING, or VALUE_NUMBER — e.g. calling getString() right after next() returned START_ARRAY or VALUE_NULL.

Common situations: Custom mapping/provider code iterating the JSON-P event stream out of order; a custom JsonProvider integration misusing the adapter; library version upgrades where parser event sequencing changed.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Target json value must a number, not " + state
• InvalidJsonException
• InvalidJsonException
• an array or object instance is expected
• Cannot create JSON element from null

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