{"record":{"id":"8acca28ec864d3f1","repo":"elastic/elasticsearch","slug":"failed-to-parse-file-docfile","errorCode":null,"errorMessage":"Failed to parse file {docFile}","messagePattern":"Failed to parse file (.+?)","errorType":"exception","errorClass":"SnippetParserException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/SnippetParser.java","lineNumber":67,"sourceCode":"\n    protected final Map<String, String> defaultSubstitutions;\n\n    protected SnippetBuilder snippetBuilder = null;\n\n    private Path currentPath;\n\n    SnippetParser(Map<String, String> defaultSubstitutions) {\n        this.defaultSubstitutions = defaultSubstitutions;\n    }\n\n    public List<Snippet> parseDoc(File rootDir, File docFile) {\n        List<Snippet> snippets = new ArrayList<>();\n        this.currentPath = rootDir.toPath().relativize(docFile.toPath());\n        try (Stream<String> lines = Files.lines(docFile.toPath(), StandardCharsets.UTF_8)) {\n            List<String> linesList = lines.toList();\n            parseLines(docFile, linesList, snippets);\n        } catch (IOException e) {\n            throw new SnippetParserException(\"Failed to parse file \" + docFile, e);\n        } finally {\n            this.currentPath = null;\n            this.snippetBuilder = null;\n        }\n        return snippets;\n    }\n\n    void parseLines(File file, List<String> linesList, List<Snippet> snippets) {\n        for (int lineNumber = 0; lineNumber < linesList.size(); lineNumber++) {\n            String line = linesList.get(lineNumber);\n            try {\n                parseLine(snippets, lineNumber, line);\n            } catch (InvalidUserDataException e) {\n                throw new SnippetParserException(file, lineNumber, e);\n            }\n        }\n        fileParsingFinished(snippets);\n    }","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/SnippetParser.java#L49-L85","documentation":"Thrown by SnippetParser.parseDoc() when an IOException occurs while reading the documentation file (e.g. the file is not readable, the path is invalid, or an I/O error interrupts the line-by-line stream read). The exception is wrapped in a SnippetParserException that names the file, preserving the cause. This is a top-level file-read failure that occurs before any line parsing begins.","triggerScenarios":"SnippetParser.parseDoc(rootDir, docFile) is called with a File that cannot be opened or read via Files.lines(...). Happens when the doc file was deleted between the file-tree scan and the parse call, permissions deny read access, the path is a directory, or the disk/FS encounters an I/O error mid-stream.","commonSituations":"A concurrent process (another build, an editor's safe-save) removes or replaces the file mid-build; a symlink is broken; the file lives on a network mount that dropped; the Gradle input snapshot listed a file that a later `clean` removed.","solutions":["Verify the file at the reported path exists and is readable: `ls -l <docFile>` and `cat <docFile>` (or open it in an editor).","Re-run the build — if a concurrent process removed the file, a clean re-run typically resolves it.","Check filesystem / mount health if the file exists but read fails (network share, disk errors).","If you intentionally deleted the doc, ensure no build input still references it (check the task's input configuration)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before parsing, assert readability:\n// if (!Files.isReadable(docFile.toPath())) fail(\"not readable: \" + docFile);","typeGuard":null,"tryCatchPattern":"// try (Stream<String> lines = Files.lines(docFile.toPath(), UTF_8)) { ... }\n// catch (IOException e) { throw new SnippetParserException(\"Failed to parse file \" + docFile, e); }","preventionTips":["Don't run `clean` concurrently with the doc test task.","Ensure doc files are committed and present on the filesystem before building.","On network mounts, verify connectivity before the build."],"tags":["docs","snippet-tests","io","build"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}