elastic/elasticsearch · error · GradleException

Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal

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.

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)

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 {asciidocFileAb
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Unexpected unconverted snippets: {foundButNotListed}
• {name}: Snippet missing a language. This is required by Elas
• {name}: No need for NOTCONSOLE if snippet doesn't contain `c

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