elastic/elasticsearch · error · GradleException

Yaml rest specs ( and ) are not equal, difference on line

Error message

Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal, difference on line: {lineNumber}

What it means

The final stage of the asciidoc/mdx parity check. After confirming equal line counts, the task walks each line and compares the asciidoc and mdx versions after normalizing `line_NN` placeholders to `line_0`. The first line where they still differ triggers this error, reporting the 1-based line number. This catches content drift between the two spec formats even when their lengths match.

Solutions

1. Open both files at the reported line number and make the content identical (ignoring only `line_NN` placeholders, which are auto-normalized).
2. Run a targeted diff: `diff <asciidoc.yml> <mdx.yml` and focus on the flagged line.
3. If the line should legitimately differ between formats, revisit whether the normalization regex needs updating — but almost always the right fix is to make them match.

Example fix

# before (asciidoc.yml line 5): GET /idx/_search
#          (mdx.yml     line 5): GET /index/_search
# after  (mdx.yml     line 5): GET /idx/_search

// Before building, normalize line_NN -> line_0 and diff line-by-line:
// for each line i: a[i].replaceAll("line_\\d+","line_0").equals(m[i].replaceAll("line_\\d+","line_0"))

When it happens

Trigger: Both YAML spec files have identical line counts but differ in content on a specific line. The comparison ignores `line_<digits>` token differences (e.g. `line_42` vs `line_7`), so the divergence is in actual request/response content.

Common situations: A typo introduced during mdx migration; an endpoint path or parameter changed in one file but not the other; whitespace or quoting differences (`'value'` vs `"value"`) that the regex normalization does not cover.

Related errors

• Couldn't find the corresponding mdx file for
• Yaml rest specs ( and ) are not equal, different line count
• Unexpected unconverted snippets
• Can't be both CONSOLE and NOTCONSOLE
• CONSOLE not paired with a snippet

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

Appendix: source

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

            }
            try {
                List<String> asciidocLines = Files.readAllLines(asciidocFile.toPath());
                List<String> mdxLines = Files.readAllLines(mdxFile.toPath());
                if (asciidocLines.size() != mdxLines.size()) {
                    throw new GradleException(
                        "Yaml rest specs ("
                            + asciidocFile.toPath()
                            + " and "
                            + mdxFile.getAbsolutePath()
                            + ") are not equal, different line count"
                    );

                }
                for (int i = 0; i < asciidocLines.size(); i++) {
                    if (asciidocLines.get(i)
                        .replaceAll("line_\\d+", "line_0")
                        .equals(mdxLines.get(i).replaceAll("line_\\d+", "line_0")) == false) {
                        throw new GradleException(
                            "Yaml rest specs ("
                                + asciidocFile.toPath()
                                + " and "
                                + mdxFile.getAbsolutePath()
                                + ") are not equal, difference on line: "
                                + (i + 1)
                        );
                    }
                }
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        });
    }

    private boolean hasMultipleDocImplementations(Path path) {
        File dir = getDocs().getDir();
        String fileName = path.getName(path.getNameCount() - 1).toString();

View on GitHub (pinned to db6a809a66)