spring-projects/spring-ai · error · RuntimeException

Failed to create new file:

Error message

Failed to create new file: 

What it means

SimpleVectorStore.save() wraps a generic IOException from Files.createFile() in a RuntimeException with the message 'Failed to create new file: <file>'. It means the JVM could not create the persistence file for reasons other than it already existing (permissions, missing parent directory, disk full).

Source

Thrown at spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java:188

	/**
	 * Serialize the vector store content into a file in JSON format.
	 * @param file the file to save the vector store content
	 */
	public void save(File file) {
		String json = getVectorDbAsJson();
		try {
			if (!file.exists()) {
				if (logger.isInfoEnabled()) {
					logger.info("Creating new vector store file: " + file);
				}
				try {
					Files.createFile(file.toPath());
				}
				catch (FileAlreadyExistsException e) {
					throw new RuntimeException("File already exists: " + file, e);
				}
				catch (IOException e) {
					throw new RuntimeException("Failed to create new file: " + file + ". Reason: " + e.getMessage(), e);
				}
			}
			else if (logger.isInfoEnabled()) {
				logger.info("Overwriting existing vector store file: " + file);
			}
			try (OutputStream stream = new FileOutputStream(file);
					Writer writer = new OutputStreamWriter(stream, StandardCharsets.UTF_8)) {
				writer.write(json);
				writer.flush();
			}
		}
		catch (IOException ex) {
			logger.error("IOException occurred while saving vector store file.", ex);
			throw new RuntimeException(ex);
		}
		catch (SecurityException ex) {
			logger.error("SecurityException occurred while saving vector store file.", ex);
			throw new RuntimeException(ex);

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Ensure the parent directory exists and is writable by the process user (Files.createDirectories on startup).
2. Fix filesystem permissions or run the process with adequate rights.
3. Check free disk space and mount state; in containers verify the volume is not read-only.

Example fix

// before
vectorStore.save(new File("/var/lib/app/store.json"));

// after
File file = new File("/var/lib/app/store.json");
Files.createDirectories(file.getParentFile().toPath());
vectorStore.save(file);

File file = new File(path);
Files.createDirectories(file.getParentFile().toPath());
if (!Files.isWritable(file.getParentFile().toPath())) {
    throw new IllegalStateException("Data dir not writable: " + file.getParent());
}
vectorStore.save(file);

try {
    vectorStore.save(file);
} catch (RuntimeException e) {
    logger.error("Could not create vector store file {}: {}", file, e.getMessage());
}

When it happens

Trigger: Calling persist() where the target directory does not exist or is not writable, the disk is full, or an I/O error occurs while creating the file.

Common situations: Misconfigured data directory path; running in a read-only container filesystem; insufficient permissions for the user the app runs as; missing parent directories.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• File already exists:
• Unknown message type:
• 'spring.ai.chat.client.tool-search-advisor.tool-index-type=v
• Documents list cannot be empty
• Error serializing documentMap to JSON.

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