{"record":{"id":"308079101c87acde","repo":"spring-projects/spring-ai","slug":"exception-wrapped-runtimeexception","errorCode":null,"errorMessage":"Exception (wrapped RuntimeException)","messagePattern":"Exception \\(wrapped RuntimeException\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-commons/src/main/java/org/springframework/ai/writer/FileDocumentWriter.java","lineNumber":90,"sourceCode":"\n\t@Override\n\tpublic void accept(List<Document> docs) {\n\n\t\ttry (var writer = new FileWriter(this.fileName, this.append)) {\n\n\t\t\tint index = 0;\n\t\t\tfor (Document doc : docs) {\n\t\t\t\tif (this.withDocumentMarkers) {\n\t\t\t\t\twriter.write(String.format(\"%n### Doc: %s, pages:[%s,%s]\\n\", index,\n\t\t\t\t\t\t\tdoc.getMetadata().get(METADATA_START_PAGE_NUMBER),\n\t\t\t\t\t\t\tdoc.getMetadata().get(METADATA_END_PAGE_NUMBER)));\n\t\t\t\t}\n\t\t\t\twriter.write(doc.getFormattedContent(this.metadataMode));\n\t\t\t\tindex++;\n\t\t\t}\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new RuntimeException(e);\n\t\t}\n\t}\n\n}\n","sourceCodeStart":72,"sourceCodeEnd":95,"githubUrl":"https://github.com/spring-projects/spring-ai/blob/98a7beda4f29d80a71c5837eb4053b03a93a46f7/spring-ai-commons/src/main/java/org/springframework/ai/writer/FileDocumentWriter.java#L72-L95","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Unwrap e.getCause() to see the underlying IOException (NoSuchFileException, AccessDeniedException, etc.)","Pre-create the output directory: Files.createDirectories(Path.of(path).getParent())","Check write permissions and disk space for the target location","Validate documents/metadataMode before invoking the writer"],"exampleFix":"// before\nnew FileDocumentWriter(\"/out/docs.txt\").accept(documents);\n// after\nFiles.createDirectories(Path.of(\"/out\"));\nnew FileDocumentWriter(\"/out/docs.txt\").accept(documents);","handlingStrategy":"try-catch","validationCode":"Path out = Path.of(targetPath);\nFiles.createDirectories(out.toAbsolutePath().getParent());\nif (Files.exists(out) && Files.isDirectory(out)) throw new IllegalArgumentException(\"target is a directory\");","typeGuard":null,"tryCatchPattern":"try {\n    writer.accept(documents);\n} catch (RuntimeException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof AccessDeniedException) { /* fix permissions */ }\n    else if (cause instanceof NoSuchFileException) { /* create dirs */ }\n    throw e;\n}","preventionTips":["Pre-create output directories before running the ETL pipeline","Verify disk space and write permissions in containers","Validate document content/metadataMode before writing"],"tags":["io","file-write","etl","document-writer","spring-ai"],"backgroundTag":"file-write-failed","analyzedSha":"98a7beda4f29d80a71c5837eb4053b03a93a46f7","analyzedAt":"2026-09-11T14:15:49.441Z","contentChangedAt":"2026-09-11T14:15:49.441Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}