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.

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)

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

• Read dsl file failed, please check if the encoding of file i
• Error processing template: ${templateName}
• Got error when creating files
• Got error when rendering template${templateName}
• Got error when creating files

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