spring-projects/spring-ai · error · RuntimeException

Error reading JSON resource

Error message

Error reading JSON resource

What it means

In the same get(String pointer) method, any IOException from reading the underlying resource stream is wrapped as RuntimeException('Error reading JSON resource'). Unlike [426] (which wraps parse failures of the node-tree path), this is the pointer-variant entry point and gives a descriptive message with the IOException as cause.

Solutions

1. Check resource.exists() and resource.isReadable() before constructing JsonReader
2. Read the resource once into a byte[] and use a ByteArrayResource for stable repeated reads
3. Catch RuntimeException and inspect getCause() (IOException) for the underlying reason
4. Verify the resolved path with resource.getDescription()/getURL()

Example fix

// before
JsonReader reader = new JsonReader(new FileSystemResource(cfgPath));
List<Document> docs = reader.get("/records");
// after
Resource res = new FileSystemResource(cfgPath);
Assert.isTrue(res.exists() && res.isReadable(), "Cannot read JSON: " + cfgPath);
JsonReader reader = new JsonReader(res);
List<Document> docs = reader.get("/records");

Assert.isTrue(resource.exists() && resource.isReadable(), "Cannot read JSON resource: " + resource.getDescription());

try {
    docs = jsonReader.get(pointer);
} catch (RuntimeException e) {
    if ("Error reading JSON resource".equals(e.getMessage())) {
        throw new UncheckedIOException((IOException) e.getCause());
    }
    throw e;
}

When it happens

Trigger: jsonReader.get("/path") where resource.getInputStream() throws — file missing, unreadable, or stream interrupted.

Common situations: Wrong classpath resource name, file moved/deleted after JsonReader construction, or reading from a flaky remote resource (HTTP/URL-based Resource).

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• IOException (wrapped RuntimeException)
• Failed to get index size for session:
• IOException (wrapped RuntimeException)
• Cannot deserialize ThinkOption from token:
• Conversion from JSON failed

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

Appendix: source

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

	/**
	 * 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)