{"record":{"id":"18ee63708fe01417","repo":"elastic/elasticsearch","slug":"couldn-t-find-the-corresponding-mdx-file-for-asci","errorCode":null,"errorMessage":"Couldn't find the corresponding mdx file for {asciidocFileAbsolutePath}","messagePattern":"Couldn't find the corresponding mdx file for (.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":519,"sourceCode":"            }\n            if (false == \"\".equals(message)) {\n                throw new InvalidUserDataException(message);\n            }\n        }\n\n        public void finishLastTest() {\n            if (current != null) {\n                current.close();\n                current = null;\n            }\n        }\n    }\n\n    private void assertEqualTestSnippetFromMigratedDocs() {\n        getTestRoot().getAsFileTree().matching(patternSet -> { patternSet.include(\"**/*asciidoc.yml\"); }).forEach(asciidocFile -> {\n            File mdxFile = new File(asciidocFile.getAbsolutePath().replace(\".asciidoc.yml\", \".mdx.yml\"));\n            if (mdxFile.exists() == false) {\n                throw new InvalidUserDataException(\"Couldn't find the corresponding mdx file for \" + asciidocFile.getAbsolutePath());\n            }\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) {","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L501-L537","documentation":"Thrown during the asciidoc→mdx migration parity check (assertEqualTestSnippetFromMigratedDocs). For every `*.asciidoc.yml` REST spec file found under the test root, the task expects a sibling `*.mdx.yml` file to exist. If the mdx counterpart is missing, the build fails with the absolute path of the orphaned asciidoc file. This enforces a 1:1 mapping between the legacy asciidoc-based YAML REST specs and the migrated mdx-based ones.","triggerScenarios":"Running the doc/REST test build in a repo that has migrated some docs from asciidoc to mdx. A new `*.asciidoc.yml` file was added (or renamed) without creating the matching `*.mdx.yml`, or the mdx file was deleted while the asciidoc one remains.","commonSituations":"Mid-migration branch where some pages have been ported to mdx and others have not; a contributor following the old (asciidoc) pattern adds a new spec without knowing the mdx mirror is required; case-sensitivity differences between the two filenames on a case-sensitive filesystem.","solutions":["Create the corresponding `<name>.mdx.yml` file next to the reported `<name>.asciidoc.yml` with the equivalent REST spec content.","If the asciidoc file is itself obsolete, delete it so only the mdx source of truth remains.","Verify the filename differs only by the `.asciidoc.yml` → `.mdx.yml` suffix (no extra dots or casing changes)."],"exampleFix":"# before: docs/set_settings.asciidoc.yml exists, no mdx counterpart\n# after: create docs/set_settings.mdx.yml with the equivalent spec","handlingStrategy":"validation","validationCode":"// For each *.asciidoc.yml under the test root, assert a sibling *.mdx.yml exists:\n// Files.exists(asciidocPath.resolveSibling(name.replace(\".asciidoc.yml\",\".mdx.yml\")))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat asciidoc.yml and mdx.yml as an inseparable pair during migration — add/remove them together.","Add a pre-commit hook or IDE check that flags an orphaned *.asciidoc.yml with no mdx sibling.","Keep filenames identical except for the suffix to avoid mismatch."],"tags":["docs","snippet-tests","mdx-migration","build","validation"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}