spring-projects/spring-ai · error · RuntimeException

Exception (wrapped RuntimeException)

Error message

Exception (wrapped RuntimeException)

What it means

FileDocumentWriter.accept writes Document contents to a file; any Exception thrown while opening/writing the file or formatting documents is wrapped in a RuntimeException. As a DocumentWriter consumer this error aborts the whole ETL pipeline step.

Solutions

1. Unwrap e.getCause() to see the underlying IOException (NoSuchFileException, AccessDeniedException, etc.)
2. Pre-create the output directory: Files.createDirectories(Path.of(path).getParent())
3. Check write permissions and disk space for the target location
4. Validate documents/metadataMode before invoking the writer

Example fix

// before
new FileDocumentWriter("/out/docs.txt").accept(documents);
// after
Files.createDirectories(Path.of("/out"));
new FileDocumentWriter("/out/docs.txt").accept(documents);

Path out = Path.of(targetPath);
Files.createDirectories(out.toAbsolutePath().getParent());
if (Files.exists(out) && Files.isDirectory(out)) throw new IllegalArgumentException("target is a directory");

try {
    writer.accept(documents);
} catch (RuntimeException e) {
    Throwable cause = e.getCause();
    if (cause instanceof AccessDeniedException) { /* fix permissions */ }
    else if (cause instanceof NoSuchFileException) { /* create dirs */ }
    throw e;
}

When it happens

Trigger: Accepting a list of documents when the target directory does not exist, the file cannot be created, the disk is full, or the path is a directory; also thrown for any unexpected exception during document formatting.

Common situations: Pointing --output or the writer path at a non-existent directory in batch jobs; read-only filesystem in containers; missing write permissions; invalid characters in generated filenames.

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

• Failed to read resource
• IOException (wrapped RuntimeException)
• java.io.IOException
• Anthropic cache breakpoint limit (4) reached. Additional…
• Anthropic Citations API requires all documents to have…

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

Appendix: source

Thrown at spring-ai-commons/src/main/java/org/springframework/ai/writer/FileDocumentWriter.java:90

	@Override
	public void accept(List<Document> docs) {

		try (var writer = new FileWriter(this.fileName, this.append)) {

			int index = 0;
			for (Document doc : docs) {
				if (this.withDocumentMarkers) {
					writer.write(String.format("%n### Doc: %s, pages:[%s,%s]\n", index,
							doc.getMetadata().get(METADATA_START_PAGE_NUMBER),
							doc.getMetadata().get(METADATA_END_PAGE_NUMBER)));
				}
				writer.write(doc.getFormattedContent(this.metadataMode));
				index++;
			}
		}
		catch (Exception e) {
			throw new RuntimeException(e);
		}
	}

}

View on GitHub (pinned to 98a7beda4f)