elastic/elasticsearch · error · SnippetParserException

Error parsing snippet in {fileName} at line {lineNumber}

Error message

Error parsing snippet in {fileName} at line {lineNumber}

What it means

Thrown by SnippetParser.parseLines() when an individual line's parseLine() call raises an InvalidUserDataException (any of the snippet-validation errors like missing language, unpaired CONSOLE/TEST, etc.). The wrapper re-throws it as a SnippetParserException that carries the source file and the 0-based line number, converting a generic validation error into one pinpointed to its doc location. Note: the line number reported is the internal 0-based index from the loop.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/SnippetParser.java:81

        try (Stream<String> lines = Files.lines(docFile.toPath(), StandardCharsets.UTF_8)) {
            List<String> linesList = lines.toList();
            parseLines(docFile, linesList, snippets);
        } catch (IOException e) {
            throw new SnippetParserException("Failed to parse file " + docFile, e);
        } finally {
            this.currentPath = null;
            this.snippetBuilder = null;
        }
        return snippets;
    }

    void parseLines(File file, List<String> linesList, List<Snippet> snippets) {
        for (int lineNumber = 0; lineNumber < linesList.size(); lineNumber++) {
            String line = linesList.get(lineNumber);
            try {
                parseLine(snippets, lineNumber, line);
            } catch (InvalidUserDataException e) {
                throw new SnippetParserException(file, lineNumber, e);
            }
        }
        fileParsingFinished(snippets);
    }

    protected void handleCommons(List<Snippet> snippets, String line) {
        if (consoleHandled(line, snippetBuilder)) {
            return;
        }
        if (testHandled(line, snippetBuilder)) {
            return;
        }
        if (testResponseHandled(line, snippetBuilder)) {
            return;
        }
        if (line.matches(getTestSetupRegex())) {
            snippetBuilder.withTestSetup(true);
            return;

View on GitHub (pinned to db6a809a66)

Solutions

1. Read the wrapped cause (the original InvalidUserDataException message) to identify which snippet-level rule was violated.
2. Open the reported file at the reported line number (remember it may be 0-based internally, but the message includes the index) and fix the underlying snippet syntax.
3. Cross-reference the cause text with the specific sibling error in this catalog (e.g. 'TESTRESPONSE not paired' → error 209) for the targeted fix.

// This is a wrapper around sibling snippet errors — catch SnippetParserException
// and read getCause() to identify and fix the underlying InvalidUserDataException.

When it happens

Trigger: Any of the snippet-level InvalidUserDataException conditions (errors 204, 205, 209, 210, 211, 212, 213, 214, 215) fires while parsing a specific line of a doc file. parseLines catches it and wraps it with file + line context so the developer sees where in the document the problem is.

Common situations: A doc author writes a malformed snippet marker anywhere in a documentation file; the underlying cause is one of the sibling errors in this list — this wrapper just adds file:line context.

Related errors

• Unexpected unconverted snippets: {foundButNotListed}
• Couldn't find the corresponding mdx file for {asciidocFileAb
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Failed to parse file {docFile}

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/bbf64a3047812d50. Report an issue: GitHub.