alibaba/spring-ai-alibaba · error · IllegalStateException

Failed to create temp directory for converter

Error message

Failed to create temp directory for converter

What it means

The MultimodalToolCallResultConverter constructor creates a temp directory (Files.createTempDirectory) to store converted multimodal artifacts. If the filesystem refuses (IOException), it throws IllegalStateException "Failed to create temp directory for converter", so the converter cannot function at all.

Source

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

	/**
	 * Default constructor for {@code @Tool(resultConverter = MultimodalToolCallResultConverter.class)}.
	 * Uses {@link OutputFormat#url}.
	 */
	public MultimodalToolCallResultConverter() {
		this(OutputFormat.url);
	}

	/**
	 * Constructor with configurable output format.
	 * @param outputFormat url (model-friendly) or base64 (inline for client)
	 */
	public MultimodalToolCallResultConverter(OutputFormat outputFormat) {
		this.outputFormat = outputFormat != null ? outputFormat : OutputFormat.url;
		try {
			this.tempDir = Files.createTempDirectory("multimodal-converter-");
		}
		catch (IOException e) {
			throw new IllegalStateException("Failed to create temp directory for converter", e);
		}
	}

	@Override
	public String convert(@Nullable Object result, @Nullable Type returnType) {
		if (result instanceof ToolMultimodalResult multimodal) {
			return toStructuredJson(multimodal);
		}
		return DEFAULT_CONVERTER.convert(result, returnType);
	}

	private String toStructuredJson(ToolMultimodalResult result) {
		Map<String, Object> map = new LinkedHashMap<>();
		if (result.text() != null && !result.text().isBlank()) {
			map.put("text", result.text());
		}
		if (result.media() != null && !result.media().isEmpty()) {
			List<Map<String, Object>> mediaList = new ArrayList<>();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check that java.io.tmpdir exists and is writable by the process user (touch a file there).
2. Free disk space or increase tmp volume size.
3. Set -Djava.io.tmpdir=/path/writable to a valid writable directory.
4. Fix container security context / readOnlyRootFilesystem settings to allow temp writes.

Example fix

// before (JVM options)
java -Djava.io.tmpdir=/nonexistent -jar app.jar
// after
java -Djava.io.tmpdir=/var/tmp/writable -jar app.jar

Path tmp = Path.of(System.getProperty("java.io.tmpdir"));
if (!Files.isDirectory(tmp) || !Files.isWritable(tmp)) { throw new IllegalStateException("tmpdir not writable: " + tmp); }

try { new MultimodalToolCallResultConverter(OutputFormat.url); } catch (IllegalStateException e) { log.error("tmpdir setup failed", e.getCause()); }

When it happens

Trigger: Files.createTempDirectory fails because java.io.tmpdir is not writable, is full, or points to a nonexistent/nonexistent-permission location; restrictive SecurityManager or sandboxed container filesystem.

Common situations: Read-only /tmp in containers, disk-full on the host, misconfigured -Djava.io.tmpdir, Kubernetes pods with emptyDir quota exhausted.

Related errors

• Failed to create root directory: {rootPath}
• Failed to delete temporary directory: {}
• Got error when creating files
• Got error when creating files
• SKILL.md not found at: {}

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