spring-projects/spring-ai · error · IllegalArgumentException

Invalid JSON Pointer

Error message

Invalid JSON Pointer: %s

What it means

JsonReader.get(String pointer) evaluates a JSON Pointer (RFC 6901) against the parsed document; if the pointer resolves to a missing node, it throws IllegalArgumentException('Invalid JSON Pointer: ...'). This signals the path syntax or structure doesn't match the actual JSON.

Solutions

1. Inspect the actual JSON structure and correct the pointer path
2. Escape special characters: '~' as ~0, '/' as ~1 in key names
3. Validate the pointer against the document before calling get(): root.at(pointer).isMissingNode()
4. Catch IllegalArgumentException and use pointer-less get() to process the whole document

Example fix

// before
List<Document> docs = jsonReader.get("/data/items"); // key is actually 'results'
// after
List<Document> docs = jsonReader.get("/data/results");

JsonNode root = JsonMapper.shared().readTree(resource.getInputStream());
if (root.at(pointer).isMissingNode()) {
    throw new IllegalArgumentException("Pointer not found: " + pointer);
}

try {
    docs = jsonReader.get(pointer);
} catch (IllegalArgumentException e) {
    docs = jsonReader.get(); // process whole document instead
}

When it happens

Trigger: jsonReader.get("/wrong/path") where the path doesn't exist, or malformed pointer syntax (missing leading '/', unescaped '~' or '/' in keys).

Common situations: Hardcoded pointers after the JSON schema changed, keys with '/' or '~' that need escaping (~1, ~0), or array index out of bounds in the pointer.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Cannot deserialize ThinkOption from token:
• Conversion from JSON failed
• Conversion from JSON to
• Conversion from JSON to
• Error parsing JSON-RPC message:

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/65c977d6f09af244. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-commons/src/main/java/org/springframework/ai/reader/JsonReader.java:128

		}
		else {
			return Collections.singletonList(parseJsonNode(rootNode, JsonMapper.shared()));
		}
	}

	/**
	 * Retrieves documents from the JSON resource using a JSON Pointer.
	 * @param pointer A JSON Pointer string (RFC 6901) to locate the desired element
	 * @return A list of Documents parsed from the located JSON element
	 * @throws RuntimeException if the JSON cannot be parsed or the pointer is invalid
	 */
	public List<Document> get(String pointer) {
		try {
			JsonNode rootNode = JsonMapper.shared().readTree(this.resource.getInputStream());
			JsonNode targetNode = rootNode.at(pointer);

			if (targetNode.isMissingNode()) {
				throw new IllegalArgumentException("Invalid JSON Pointer: " + pointer);
			}

			return get(targetNode);
		}
		catch (IOException e) {
			throw new RuntimeException("Error reading JSON resource", e);
		}
	}

}

View on GitHub (pinned to 98a7beda4f)