{"record":{"id":"374e83878619de13","repo":"elastic/elasticsearch","slug":"yaml-rest-specs-asciidocfile-and-mdxfile-are-374e83","errorCode":null,"errorMessage":"Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal, difference on line: {lineNumber}","messagePattern":"Yaml rest specs \\((.+?) and (.+?)\\) are not equal, difference on line: (.+?)","errorType":"exception","errorClass":"GradleException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":538,"sourceCode":"            }\n            try {\n                List<String> asciidocLines = Files.readAllLines(asciidocFile.toPath());\n                List<String> mdxLines = Files.readAllLines(mdxFile.toPath());\n                if (asciidocLines.size() != mdxLines.size()) {\n                    throw new GradleException(\n                        \"Yaml rest specs (\"\n                            + asciidocFile.toPath()\n                            + \" and \"\n                            + mdxFile.getAbsolutePath()\n                            + \") are not equal, different line count\"\n                    );\n\n                }\n                for (int i = 0; i < asciidocLines.size(); i++) {\n                    if (asciidocLines.get(i)\n                        .replaceAll(\"line_\\\\d+\", \"line_0\")\n                        .equals(mdxLines.get(i).replaceAll(\"line_\\\\d+\", \"line_0\")) == false) {\n                        throw new GradleException(\n                            \"Yaml rest specs (\"\n                                + asciidocFile.toPath()\n                                + \" and \"\n                                + mdxFile.getAbsolutePath()\n                                + \") are not equal, difference on line: \"\n                                + (i + 1)\n                        );\n                    }\n                }\n            } catch (IOException e) {\n                throw new RuntimeException(e);\n            }\n        });\n    }\n\n    private boolean hasMultipleDocImplementations(Path path) {\n        File dir = getDocs().getDir();\n        String fileName = path.getName(path.getNameCount() - 1).toString();","sourceCodeStart":520,"sourceCodeEnd":556,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L520-L556","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open both files at the reported line number and make the content identical (ignoring only `line_NN` placeholders, which are auto-normalized).","Run a targeted diff: `diff <asciidoc.yml> <mdx.yml` and focus on the flagged line.","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."],"exampleFix":"# before (asciidoc.yml line 5): GET /idx/_search\n#          (mdx.yml     line 5): GET /index/_search\n# after  (mdx.yml     line 5): GET /idx/_search","handlingStrategy":"validation","validationCode":"// Before building, normalize line_NN -> line_0 and diff line-by-line:\n// for each line i: a[i].replaceAll(\"line_\\\\d+\",\"line_0\").equals(m[i].replaceAll(\"line_\\\\d+\",\"line_0\"))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["After porting a spec, run a normalized diff (`sed 's/line_[0-9]*/line_0/g'`) on both files.","Change content in both files in lock-step; never edit only one side.","Beware quoting/whitespace differences that the regex normalization does not cover."],"tags":["docs","snippet-tests","mdx-migration","build","validation"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}