alibaba/spring-ai-alibaba · error · RuntimeException

Failed to read resource

Error message

Failed to read resource

What it means

In MultimodalToolCallResultConverter.mediaToMap(), when media data is a Spring Resource, its content is read via getContentAsByteArray(); an IOException there is rethrown as RuntimeException "Failed to read resource". It means the binary content backing the resource could not be loaded.

Solutions

1. Verify the resource location exists and is readable before returning it from the tool.
2. Prefer passing raw byte[]/Media instead of a lazily-resolved Resource when the source may vanish.
3. Check that classpath resources are on the classpath at runtime (jar packaging includes them).
4. Catch this RuntimeException and map to a tool error message for the model.

Example fix

// before
return new UrlResource("file:///tmp/gone.png");
// after
Resource r = new UrlResource("file:///tmp/gone.png");
if (!r.exists()) { throw new IllegalStateException("media file missing: " + r); }
return r;

if (r instanceof Resource res && !res.exists()) { throw new IllegalStateException("missing resource: " + res); }

if (data instanceof Resource res && res.exists() && res.isReadable()) { /* safe to convert */ }

try { converter.convert(result, returnType); } catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to read resource")) { /* return tool error to model */ } }

When it happens

Trigger: Passing a Resource (e.g. UrlResource, ClassPathResource, FileSystemResource) whose backing file/stream is missing, unreadable, or whose URL connection fails during conversion of a ToolMultimodalResult.

Common situations: Deleted or moved temp files referenced by URL resources, classpath resources packaged incorrectly, expired remote URLs, permission issues on file resources.

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

• Cannot convert resource to file system path:
• Cannot convert resource to file system path
• Cannot convert resource to file system path
• Currently Spring AI ToolResponseMessage only supports text…
• 搜索请求执行失败

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/2c1981c180b8a4ec. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/tool/multimodal/MultimodalToolCallResultConverter.java:146

		}
		else if (data instanceof URL url) {
			try {
				putUriOrEncodeToDataUrl(url.toURI(), mimeTypeStr, itemMap);
			}
			catch (java.net.URISyntaxException ex) {
				putUriOrEncodeToDataUrl(URI.create(url.toExternalForm()), mimeTypeStr, itemMap);
			}
		}
		else if (data instanceof String s && isUriLike(s)) {
			putUriOrEncodeToDataUrl(URI.create(s), mimeTypeStr, itemMap);
		}
		else if (data instanceof Resource resource) {
			handleBytes(() -> {
				try {
					return resource.getContentAsByteArray();
				}
				catch (IOException e) {
					throw new RuntimeException("Failed to read resource", e);
				}
			}, mimeTypeStr, itemMap);
		}
		else if (data != null) {
			try {
				byte[] bytes = media.getDataAsByteArray();
				if (bytes != null && bytes.length > 0) {
					handleBytes(() -> bytes, mimeTypeStr, itemMap);
				}
			}
			catch (IllegalStateException e) {
				String s = data.toString();
				if (isUriLike(s)) {
					putUriOrEncodeToDataUrl(URI.create(s), mimeTypeStr, itemMap);
				}
			}
		}
		return itemMap;

View on GitHub (pinned to f82da0b50f)